Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / JORF21-1.ZIP;1 / JORFDOCS.ZIP / JORFMAN.TXT

Wrap

Text File | 1993-07-05 | 631.8 KB | 22,384 lines

The JORF(R) Manual As a member of the Association of Shareware Professionals we are required to provide a full manual on disk in the shareware version. Please feel free to print this manual on your dot matrix or laser printer. It is about 350 pages long. Since the JORF Company has spend considerable time, money and effort creating this product, we will be proud to send you a real manual, with graphic screen displays, printed and bound, when you paty our very reasonable registration fee. Free Shareware Version Free On Disk Registered DOS Only Version $45 Printed Registered DOS/Windows Version $85 Printed JORF Developer's Kit $170 Printed Thank you all advance for your support in the development of JORF and the success of The JORF Company. Wayland Bruns The JORF Company 25858 Elwood Road Colton, OR 97017 (503) 824-5673 Copyright(c) 1993 by The JORF Company. All Rights Reserved. PRINTERS NOTICE: All legitmate copyies of The JORF Manual are printed by the JORF Company and will not carry this notice. Photocopying this manual is a violation of the copyright act. JORF(R) is a Registered Trademark of The JORF Company. Other JORF Company products are trademarks of The JORF Company. Other brand and product names are trademarks of their respective holders. Please print this on recycled paper The JORF License Agreement COPYRIGHT. The JORF Interpreter and JORF Developer's Kit are owned by The JORF Company and are protected by United States copyright laws and treaty provisions. By using this software you are agreeing to be bound by the terms of this license. If you do not agree with this license, you may return all materials to The JORF Company for a full refund. GRANT OF LICENSE. The JORF Company grants you the right to use one copy of the software for each paid registration. You may install the software on more than one computer, but you may use only one copy at a time. You must register each copy of the software that you use at any one time to create new programs. TRIAL COPIES. The JORF Interpreter and JORF Language Tutorial may be copied and distributed on a trial basis. If you use the software to create programs then trial is over and you must register your copy with The JORF Company. You may freely give copies to your friends so they can try it. If they use it to create new programs they must register it. RUNTIME MODULE. The JORF Company grants you the royalty free right to distribute the runtime module JORF.EXE with your programs provided that; (a) your program does not directly compete with JORF Company products; (b) your program displays a copyright message that includes the word "Copyright", a "(C)", the year, your name and the phrase "All Rights Reserved"; and (c) you agree to indemnify, hold harmless, and defend The JORF Company from and against any claims or lawsuits, including attorney's fees, that arise or result from the use or distribution of your program. OTHER RESTRICTIONS. Persons or corporations involved with the production of biological, chemical or nuclear weapons may not use JORF Company Products. JORF Company Products may not be used in any type of weapons system. LIMITED WARRANTY LIMITED WARRANTY. The JORF Company warrants that the software will perform substantially in accordance with the accompanying written materials for a period of 90 days from the date of receipt. Any implied warranties on the software are limited to 90 days. Some states do not allow limitations on duration of an implied warranty, so the above limitation may not apply to you. CUSTOMER REMEDIES. The JORF Company's entire liability and your exclusive remedy shall be, at The JORF Company's option, either (a) return of the price paid or (b) repair or replacement of the software that does not meet The JORF Company's Limited Warranty and which is returned to The JORF Company with a copy of your receipt. This Limited Warranty is void if failure of the software has resulted from accident, abuse, or misapplication. Any replacement software will be warranted for the remainder of the original warranty period or 30 days, whichever is longer. NO OTHER WARRANTIES. THE JORF COMPANY DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE JORF SOFTWARE AND THE ACCOMPANYING WRITTEN MATERIALS. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS; YOU MAY HAVE OTHERS WHICH VARY FROM STATE TO STATE. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL THE JORF COMPANY OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, SPECIAL, INDIRECT INCIDENTAL OR CONSEQUENTIAL DAMAGES, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS PRODUCT, EVEN IF THE JORF COMPANY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. Installation The JORF Company ships three interpreters and a developer's kit. The JORF interpreter is the smallest and fastest version of the interpreter. The JORF386 and JORFWIN interpreters act as a pair to provide complete interpreter and debugger facilities in two operating system platforms. Finally, the JORF Developer's Kit includes link libraries and batch files that enable you to compile your JORF application programs. Requirements The JORF and JORF386 versions of the interpreter run on IBM PC XT, AT 386 and 486 computers. JORF can be run on a floppy disk system but that is really painful; a hard disk is highly recommended. JORF386 requires a 386 computer. The JORFWIN version of the interpreter runs under Windows 3.1 and above. It requires a 386 style computers using Windows in 386 Enhanced mode. Using JORF on a Floppy Drive You can use JORF on a dual floppy disk system. To do this, put the JORF.EXE program on one floppy disk, and the sample files on another. You will not be able to use ON-Line help. You may need to keep large programs like the TUTORIAL on separate disks. When starting JORF, please be sure you have 100K free on your floppy disk. That space will be used by the memory-swap file. Your programs can be run from the B drive. If you need further instructions, write or FAX the JORF Company. Hard Disk Installation The DOS and Windows distribution has two 5 ¨ disks or one 3 ´" disk. To install, create an appropriate subdirectory, copy and unpack the files that are appropriate. Create a JORF subdirectory: MD \JORF Copy files to that subdirectory: COPY A:*.* Unpack standard 386 interpreter: PKUNZIP JORF386 and/or Windows interpreter: PKUNZIP JORFWIN Always unpack sample files: PKUNZIP JORFFILS Optional help files: PKUNZIP JORFHELP Optional Manual-on-disk: PKUNZIP JORFDOCS Save space by deleting the Zip files: DEL *.ZIP Installation i Installation Batch File If you can place the installation disk in floppy drive A:, and you have a hard disk drive C with about 2 Megabyte free, you can use INSTALL.BAT. This file creates a directory called C:\JORF and places the appropriate files in that directory. a. Place the floppy disk in drive A: b. Type A: to log to drive A. c. Type INSTALL to start the installation. d. Select version to install from the menu. e. If installing from low density disks, insert Disk 2 when prompted. To Run The JORF Interpreter You can run the DOS version of interpreter by logging to the appropriate directory and typing JORF. To run the 386 version, type JORF386. To run the Windows version of the interpreter, you must add the JORFWIN application in the Program Manager. From the File menu, select New Application. Type JORF for the name, and C:\JORF\JORFWIN.EXE (using the appropriate disk and directory) for the file to run. Click Done to finish adding the application. The first time you run JORF, you should select TUTORIAL.J to load and run the JORF Tutorial. To Exit from The JORF Interpreter Pressing Alt-X will exit from any JORF program. You can exit from the current screen by pressing the Esc key. The JORF Initialization file If you have any problems with screen colors or display in the DOS version, you should turn to Appendix D for information about adjusting your JORF.INI file. The JORF Manual (Shareware Disk Version) ii Version 2.1 Release Notes Version 2.1 was released in March, 1993. The following notes are for people who have used earlier versions so that they know what areas have been improved and changed. Perils and Pitfalls (Changes that affect working code) A new keyword Poly must now be used for polymorphic method calls. In prior versions, polymorphic calls were indicated by having no class in front of the method name. For instance, a polymorphic call to a print a variable used to be Print(A), but now must be changed to Poly:Print(A). This change was made to increase program speed and make polymorphic calls less ambiguous. The File:Read() and File:Write() functions no longer use the Level argument. All references to these functions in your code should be modified to reflect this change. If you have used these functions you probably agree that this argument was redundant. File:Map() now acts more like and "Open" function, and a new File:Close() function has been added. File:Access() has been renamed File:Exist(). These changes were introduced to make it easier to read and write various types of data files. The Time:Get() and Time:Set() functions are totally different. Two internal types have been added for time and date. Conversions have been made even more flexible to make it easier for stored date fields to be displayed according to the desired format of the user. Time and Date addition and subtraction routines have been introduced. The action of the Tab key has been modified slightly. When you are editing text in a data entry window, you must now use Alt-Tab to move the cursor eight spaces. The Tab key now carries you to the next field. In prior versions, there was no way to Tab out of text fields on a data entry screen. New Features The interpreter runs as much as 10 times faster for some processes. A lot of work has gone into decreasing disk access so people can run the JORF interpreter from a floppy disk. The JORF386 interpreter uses 32-bit processing and VROOM to increase speed and use high memory. The JORF386 version must be run from a hard disk on a 386 or 486 computer. Clipper style DBF/DBT/NTX file support has been added. Although it would seem intuitive to support dBASE IV format, the vote from the programmer community indicated that there are far more Clipper applications than dBASE IV applications. The support of Clipper files enables programmers to duplicate and add to Installation iii existing Clipper applications without making their existing programs obsolete. People who use FoxBase and dBASE files can still use JORF, but will have to avoid the Floating Point formats and will not be able to use compatible indexes. The Win:Attr() function now allows you to set any of 16 background and foreground colors. The "Blink" attribute has been turned off under DOS, yielding 8 more background colors, including dark gray and yellow. The internal format of the JORF Pointer has been augmented. New types include a date type and a time type. Partially implemented is a BLOB (Binary Large Object) type that will enable developers to store large strings and other binary data. Under the new system there is still room for eight more internal data types for future expansion. The Program Editor now features colored syntax highlighting, with different colors for functions, constants, numbers, punctuation and comments. This highlighting makes it easier to read the code, and gives an instant "syntax check" to be sure you spelled everything correctly. A "Type" and "Format" commands have been added to field input to allow data to be type checked and reformatted automatically when entered. This capability allows numbers to be entered in numeric format, and automatically redisplayed with commas and decimal positioning. The JORF to C language translator is now a separate program JTOC.EXE. Much work has been done to decrease the size of translated modules. The libraries have been optimized with smaller module sizes to increase speed under VROOM. The internal storage format of a structure has been modified to be more compact. The format change is automatic when a structure is written. You can reformat a file by rebuilding it. Reformatting the Contact Manager JCM files yields new files that are 25% the size of the old files. New sample programs include a Calendar date picker, a calculator, and a screen color setting program. The Contact manager has split into two versions, MAILLIST.J is a simple version, and CONTACT.J is more complex. Some file handling programs have been added. On-Line help has been expanded. The JORF Manual (Shareware Disk Version) iv Table of Contents Installation Chapter One Welcome to JORF 1 Chapter Two Getting Started 15 Chapter Three JORF Math 31 Chapter Four The Window Manager 51 Chapter Five JORF Functions 85 Appendix 330 Index 367 Installation v Chapter One Welcome to JORF Welcome JORF is an acronym for Josephine's Recipe Filer. Josephine is a tan pygmy goat who lives at the foot of the Cascade Mountains in Oregon. She does not file recipes but instead she dances and plays in the sunshine. Her message is simple; Lighten up, Eat, Dance, Baaaah. People laugh at Recipe Filers. What a stupid use for computers they say. If think a moment, you will realize the joke is on those that laugh. Recipes are trivial "programs" that regular people can understand and use. The problem is that they have unlimited ingredients and unlimited text, which makes it difficult to file them with a relational data base manager. Recipes are not numeric enough to file with a Spreadsheet. And Recipes need to be indexed so you can not file them using a Word Processor. Instead of being trivial recipes are a good example of everyday data that is too complex for most currently available computer tools. JORF was written by me, Wayland Bruns, and The JORF Company is another name for me and Josephine. We are open only part time, Monday through Wednesday from 9-5 Pacific Time. The phone number is (503) 824-5673. You don't have a serial number, because I keep all registrations by name. Feel free to call or write at any time, and I will be happy to talk to you if I have time. Not that I have much time any more, please write if you can. Introduction The JORF Language is a application building language for people want to create DOS and Windows programs. It is an Object Oriented Programming language, featuring one data type, multiple inheritance, classes, structures and polymorphism. JORF brings the power of OOP into the hands of people who will never have the Installation 1 time to learn complex OOP languages like C++ and Smalltalk. JORF gives you a way to program for Windows, without having to understand the quirks of this complicated computing environment. Basic Rules Indentation controls program flow. Labels are not sensitive to letter case. The end of line is the end of the line. Comments begin with a pipe symbol. Parentheses surround parameter lists. Key Words Jorf The default data type. Class Declares a structure (record). Parent Designates a parent class. Index Designates an index field. The JORF Language is not a scripting language. It is a formal structured language that supports pointers, arrays, local data and recursion. It is the only Windows language (that I have seen) that does not require a complex WinProc message handling routine. The JORF Language uses a single data type, called a Jorf Pointer, that can hold integers, floating point numbers, strings, and blocks of text. Object Oriented Classes are defined by the programmer, and may include Structures, objects with more than one element. Windows Programming The Windows culture is the culture of the WinProc; programs dominated by massive unstructured switch statements that handle esoteric message flags. As different products convert to Windows, they unquestioningly adopt the WinProc culture. BASIC, the language for the beginner, becomes Visual Basic, a language for precious few. C programs become full of global values. MS-Windows is so complicated that not even full time programmers can learn every command and every subsystem. This leaves no time for Windows programmers to learn about their customers. They are doomed to write programs that cannot meet the particular needs of these customer. The legacy of Windows threatens to be like the legacy of UNIX; expensive techies, weak programs. The JORF Manual (Shareware Disk Version) 2 JORF Programming in Windows You won't see a WinProc in a JORF language program. You won't see anything more complicated than a procedural Win:Add function, that creates a window with menus, buttons and data entry prompts. The JORF Window functions run identically under both MS-Windows and DOS Text mode. The Windows implementation of JORF is a subset of the opportunities available under Microsoft Windows. The JORF Language supports the Windows "Look" while supporting just a small subset of Windows functions. Complexity is eliminated by eliminating complex functions, and limiting the look of the functions available. The following program HELLO.J runs identically in both DOS and Windows: Hello:Start Msg:Add ("Hello", "Ok") Welcome to the wonderful world of JORF! Return The program looks like this: Under DOS Under Windows The same JORF programs runs identically under DOS, with the same buttons, menus, mouse capability, and data structure. This means that people who have slower and smaller computers can still run your programs. Programs run considerably faster under DOS, but are not as pretty and multiple programs cannot be run at one time. Program Logic and Flow There are six key words in The JORF Language; Class, Index, Parent, Jorf (the default data type), And and Or. These are supplemented with Standard Library Functions written in the C language and compiled into The JORF Interpreter. This is how If, While, Win:Add, and Move:To are implemented. Starting a Program Programs always start with the Start method. This method may belong to a class with the same name as the source file name, or may be Jorf:Start. Chapter One - Welcome to JORF 3 Labels Class, Method, and Variable names are not case sensitive. Names can use letters, numbers or the underscore character. Names cannot start with a number. The following table demonstrates some legal and illegal names: Legal Labels Illegal Labels Reason MyProgram My Program Embedded space not allowed Num1 1Num Cannot begin with a number Num_2 Num-2 Punctuation illegal except for A_1 A$1 underscore character _Foo CAN begin with underscore (Parentheses) Parentheses put items together to avoid any confusion about what order to do math and other things. 2 + 3 * 4 | Equals 14 (2+3) * 4 | Equals 24 Parentheses are also used to enclose the parameter list for a method. If there are no parentheses, the function is assumed to have no parameters. Win:Add("MyWindow") | Function with parameter Win:Add() | Function without parameter Win:Add | Same thing - empty | parentheses are optional The JORF Manual (Shareware Disk Version) 4 Indentation Indentation controls program flow. You must use proper indentation for your program to work correctly. That means you won't have to type in curly brackets or ENDDO statements at the end of your branching and looping structures. This example shows a For loop and nested If structure. No "Next" is necessary because the loop is closed by the unindented command after the loop. Binary:Start New Char Win:Add ("BINARY VALUES", 4, 4, 19, 60, Here) For (Char = 0 Thru 255) If (Char > 0 and (Char % 16 == 0)) Win:Pause If Kbd:Got == "Esc_Key" Break Str:Put(" Character= {To:Str(Char,'000')} Symbol= ") Char:Put(Char) Str:PutLine(" Binary= {To:Str(Char,'0000 0000',2)}") If Kbd:Got != "Esc_Key" Win:Pause Return (Ok) Here is an example of the program output from BINARY.J. This counts up from zero to 255 displaying each character and it's equivalent binary expression. Another related example is ASCII.J which displays a table of ASCII codes. Windows programmers will note that JORF displays the IBM character set, not the ANSI character set that Microsoft wants us all to switch to. Parameters Parameters are normally passed by value, so that subroutines can freely modify the value without affecting the same in the calling routine. Parameters may also be passed by reference so that the Chapter One - Welcome to JORF 5 subroutine explicitly modifies the value. Use this when you need more than one return value from a called method. Unlike the C or Clipper languages, JORF Programs mark variables passed by reference in the parameter list of the subroutine. Once a parameter is declared by reference (using an asterisk) no further notation is necessary for the data to be modified in the calling method. ByRef:Start | This test program shows the result of method that | uses a parameter (Foo) that is passed by reference. | Usually, parameters are passed by value, so that any | changes to the variable do not affect the calling | method. Sometimes you want to affect the variable | in the calling method, which is why you want to | specify a parameter passed by reference. New (Foo,Fee) Foo = 7 Fee = 7 Win:Add("Example of Passing by Reference",0,0,9,56,Here) Str:PutLIne('In this example, the called method specifies that Foo be') Str:PutLIne('be passed by reference, and Fee be passed normally.') Str:PutLIne() Str:PutLine(" At start Foo is {Foo}, Fee is {Fee}") Str:PutLine() ByRef:Increment(Foo, Fee, 8, 8) Str:PutLine(" At end Foo is now {Foo}, Fee is {Fee}") Win:Pause Return ByRef:Increment(*Foo,Fee) ++Foo ++Fee Str:PutLine(" In Increment method Foo is now {Foo}, Fee is {Fee}") Str:PutLine() Return (Ok) When you run this program, it looks like this. You can see that Foo and Fee both start out as 7, and they are both incremented to 8 in the subroutine ByRef:Increment. The difference comes when the subroutine is ended and the program returns to the ByRef:Start method. At this point, Fee is still 7 because it was passed by value, and therefore remains unchanged by the subroutine. But Foo has been changed to 8 because it was passed by reference. The JORF Manual (Shareware Disk Version) 6 Data Base Manager The JORF Interpreter is a transparent data base manager. The structure definition acts as a record definition, with the different elements acting as fields. The key word Parent can be used to inherit fields and indexes from another class. The key word Index creates an automatic index on a field in a structure. Other class names will designate the class of a field, which influences the editing and formatting routines that are used. Class:MyRecord | Creates new Class called "MyRecord" Index:Contact | Field name "Contact" is an index Parent:Addr | Inherit "Addr" fields and indexes Phone:Work | Field name "Work" is class "Phone" Phone:Home | Field name "Home" is class "Phone" Index:PIndex | Field name "PIndex" is an index. Type | Field name "Type" is Just a field Note | Field name "Note" can even be text It is normal for a single file to contain several classes. Data files also contain the associated indexes for those classes. Each class can have many indexes. Both data and indexes are stored together in a single file, and contain relative pointers so the file name and location may be changed. Limit Real Limit Practical Limit Records per file 232 500, 5000, 50,000+ Fields per record 2048 100 Classes per file Unlimited 1 - 10 Indexes per Class 2048 1 - 10 Parents per Class 2048 1 - 5 Length of a string field 10K 4048 Text field length limit 32K Lines 2000 Lines Array elements 232 10,000 Integer size long Floating point size double Structure elements can be Integers, Floating point numbers, Strings, Multiple Line Text and Arrays. Arrays can contain sub- arrays or other structures. The practical record limit depends on what you are using the records for. If you need lightning fast access, as in list boxes Chapter One - Welcome to JORF 7 or quick pick lists, you better keep your files below 500 records. There is a discernable slowdown when a file goes over about 1500 indexes, or about 500 records in a file that keeps three indexes per record. Seek speed remains under a second for larger files, but programs that use large files (over 5000 records) should avoid long pick list displays since it takes some time to read all the records on the list. Memory Management Why is it my fault when my computer runs out of memory? It is not my memory, why is it my fault? Why do I have to "Open" a file just to read data from it? What exactly is "Opening"? Why can't I have two records available at the same time? The JORF language handles its own memory, and your reward is freedom to allocate large structures, arrays and text. The JORF memory can flush variables, methods, windows, internal values, and even the program stack to disk whenever memory gets scarce. Data is read from file when you reference it, so there is no need to "Read" it, and no difference between a "memory variable" and a field in a record. Text and Arrays are held in sparse chunks in memory. Arrays are held 16 elements at a time, and Text is held 4096 bytes at a time. Arrays remain fast even as they grow to enormous sizes. Text editing remains reasonably fast for text up to 100K. Object Persistence The JORF language can handle data storage almost automatically. Most data in JORF is held in Structures, units of data with multiple elements. Structures in JORF are the equivalent of records in any data base language, except that in JORF you can store more than one structure type in a single data file. Structures are created as memory variables, and are stored using the Jorf:Write function. Index fields may be declared in the structure definition. When indexes are declared, the interpreter automatically handles index maintenance whenever the structure is changed. The JORF language has some unusual rules for structures in data files. These rules are quite different than those used in relational data bases. All fields in a JORF structure must be stored in the same file. If a structure contains a pointer to another structure, both structures must be contained in the same file. If you attempt to point to a structure from another file, for instance, an invoice record points to a customer in a customer file, a copy is made so the entire customer structure will be duplicated in the invoice file. The only way to store The JORF Manual (Shareware Disk Version) 8 the information in separate files it to create relational "link" fields as you do in a relational data base. The other rule to remember is simply that all indexes are stored in the same file as the structures. The reason for this is simple. A common problem in application programs happens when a user restores one related file without restoring all files necessary. This often results in an Invoice file, for instance, referencing customers that don't exist in a restored customer file. By keeping related information together, I hope to help people avoid this type of file synchronization problem. Rule Based System The JORF Language includes indexing based on Object-Attribute-Value rule triplets. This system is used for data base indexing and forward and backward chaining rule based systems. The rules also contain probability and a conditional pointer for flexibility in expert systems applications. Network Applications The JORF language was built to create networked applications. (Always strikes me odd and unrealistic when a language like db:Fast is introduced as single user only.) Using JORF in single user mode is faster, especially on slow computers, so when you first start the system you will be in single user mode. To switch to multi-user network mode, you need only change your JORF.INI or JORFWIN.INI file. Just change the "MULTIUSER=NO" line to "MULTIUSER=YES". If you are using JORF on a non-networked drive, you will have to load the MS-DOS utility SHARE. Just put the word SHARE in your AUTOEXEC.BAT file. If you want to get fancy, you can load share into high memory using the LOADHIGH command. Even if you use MS- Windows, you must load share. The JORF interpreter will tell you if SHARE is not loaded correctly. When you switch the MULTIUSER flag, the JORF language automatically stops caching and starts file locking for index operations. This will slow the program down unless you have a disk cache active (as most networks do). If you have MS-Windows on your system, you are probably using SMARTDRV (from the "If it is in the name it isn't true" department of Microsoft). SMARTDRV is adequate to regain the lost speed. The other part of Networking is the locking of Structures that are being edited. If Jan is editing a customer structure, you must be sure that Bob cannot start editing the same structure at the same time. In a "Windows" type environment, locking is Chapter One - Welcome to JORF 9 complicated by the fact that Jan can change a field in a structure, and then pop up an entirely different window and start a different operation without leaving the field that she is on. That means that the programmer must arrange the program so that pull down menu and hot key options are only available after the structure change is complete and the structure is written to disk. The sample program CONTACT.J shows how to use the INPBEFORE and INPAFTER screen commands to check the locking before and after every field is changed by the operator. In JORF, the record locking functions are Jorf:Lock to lock a structure for changing, Jorf:Write to write and unlock the structure, and Jorf:Unlock to unlock and re-read a structure when an operator decides to abort a change operation. A proper network application will be sure that all change operations are made on locked records. More information on record locking is available in the reference areas for these functions. The JORF File:Lock function can be used to lock an entire data file, and when you are done with changes you can use File:Unlock to release the lock. These functions are best used for text file editing and for operations that change every structure in a file. The Jorf:Rebuild function uses a file lock automatically. dBASE/Clipper files Version 2.1 of the JORF language introduces support for dBASE III files and Clipper NTX indexes. This support is intended to allow Clipper programmers to create utilities and modules for existing Clipper applications. In theory, with fewer lines, there will be fewer bugs. JORF gives you some access to high level Window Management routines that replace the "By-Hand" data entry checking that dominates many Clipper applications. The JORF language has true "User Defined Functions" that are currently lacking in FoxPro, and has a reasonable compiled program size (A minimum of 250K, with most applications weighing in at about 500K to 1MB). While the JORF language will never replace the dBASE language as a programming tool, the dBASE file support allows you to experiment with programs while maintaining file compatibility with your existing application. Math And Logic Many Object Oriented Languages treat math operators as Method Calls. This is really cute when you use "+" to concatenate a structures, and "=" to assign them. However, this is not easy to implement and leads to a host of problems. Instead, the JORF The JORF Manual (Shareware Disk Version) 10 Language uses a stack oriented math system like that in BASIC, PASCAL and C language. Order of Operations The operations are handled in the following order: -> Pointer References [] Array References - ! ~ ++ -- Unary operations * / % Multiplication + - Addition < > <= >= Evaluation = == != <> Equality && ?? Logical AND and OR = Assignment Assignment is by value for simple elements and constants, and by reference for structures. Throughout JORF, structures are handled as pointers. Structures can be moved as "buffers" using the Jorf:Move function. The JORF Language sees numbers as numbers, and automatically handles integer and floating point conversions. Integer division, and integer addition and multiplication of large numbers may yield floating point results. You can manually convert numbers using the To:Num, To:Str, To:Char and To:ASCII commands. The Num:Min, Num:Max, Num:Int, Num:Abs, and Num:Pow functions give you extra capabilities with both integer and floating point values. International Considerations I take this space to remind you, as a programmer, that computers are used the world around. Although most programs are written in English, and users often become used to english language prompts in a program, the data they enter and use will be in their native formats. That means that some thought should go into designing Address areas, dates and numeric formats. To aid in handling date formats, the JORF To:Date and Date:Str functions use a format string that allows you to easily control the format. The JORF language can store dates in a native data type. Whenever that date is displayed, however, it can be freely reformatted to suit the desires of the operator. The formatting system even allows you to change month names and dynastic year origin, so that you can easily accommodate string dates in many languages. Chapter One - Welcome to JORF 11 Numeric formats are simpler because Arabic numbers are used for mathematics throughout most of the world. Some countries, however, use the comma for a decimal point, and the period is an indicator for thousands. When writing a JORF language program, you will have to write all numbers in the American period-decimal style. If the user specifies "Decimal=," in the JORF.INI file, however, all numbers displayed and entered will be in the requested comma-decimal style. This system allows programmers to write in a standard way and still accommodate users who wish to see their numbers notated differently. See the reference section entries for the Num:Str and To:Num functions, and Appendix D Decimal= section for more information on comma-decimal formatting. The Window Manager The biggest feature of the JORF Language is the Window Management system that handles pull down and pop up menus, hypertext prompts, radio buttons, check boxes, and data entry fields. This system is handled entirely within the Win:Add function. The syntax of the JORF window management system uses one command line for each data entry feature on the screen. Command lines start with a command word and a quoted prompt string. Various values can be added on the same line, or on indented lines below the command. Different commands use different values. Data entry will be in the order of the command lines. Event:Add ("EditKey") Win:Add ("Title", Row, Col, Len, Wid, Level) Command:"Prompt", Option:"value", Option:"value" Option:"More Values can be Indented" Option:"For as many lines as necessary" Command:"Prompt", Option:"value", Option:"value" Command:"Prompt", Option:"value", Option:"value" You can also place a text paragraph at the bottom. The system looks for the keyword and colon (:) character and if they are absent will print the rest of the indented screen definition as a text paragraph. You can embed commands within text by enclosing some commands in {Command:"Curly brackets, Option:"value"}. This can be used for hypertext prompts and buttons that are embedded in the text. Return Windows programmers may note that under windows, JORF uses the Windows menu handling system. However, the JORF interpreter handles data entry fields without using the Windows Dialog box system. Radio Buttons and Check boxes are a hybrid, where the The JORF Manual (Shareware Disk Version) 12 buttons are defined as child windows, but the prompts and keystrokes are handled by the JORF interpreter. The JORF Programming Environment The JORF interpreter contains a built in program editor and source level debugger. To start the debugger, press Ctrl-Break at any time. The debugger has a menu with options to allow you to edit the program, examine the stack, or trace through the code. Both the debugger and the editor are written in the JORF language, and they are a good example of some capabilities in the language. The debugger allows you to edit live programs, rewind the program pointer, and execute your new code without restarting the program. Using an Outside Editor You can also use an outside editor to edit JORF programs. Simply edit the appropriate source file. The next time you run it the interpreter will automatically reload your changes. Translating to C The JORF Company offers a developer's kit that allows you to translate and compile your JORF program code. With this kit, your code will be translated to C. You then can use any of the listed compilers below to compile the program to be a true EXE file. You can also use the kit to link your JORF modules to C program modules to create a combined application program. Cautionary note: JORF program code does not translate into clean C code any more than C code translates into clean assembler code. A JORF variable can be a string, number or multiple line text, and has an ambiguous data type when declared. C language variables are never ambiguous. To keep compatibility with the language, a variable in JORF remains a JORF pointer in C, and is not translated to the C integer or string data types. For this reason, C programs in JORF only get moderate boost (about 5 times faster) from the compiling process. The primary benefit of compiling is that you can distribute the resulting EXE file without royalty and without your customer being able to see or modify your source code. The Developer's kit is ideal if you want to compile small programs (under 100K source code). It comes equipped with batch Chapter One - Welcome to JORF 13 files that make it easy to compile DOS and Windows programs, even if you know nothing about the C language. If you need to link outside routines in your program you will have to know something about the C language to be successful. If your program is large (over 100K source code) you will probably have to split it into multiple modules and compile them separately. This process requires building a Borland Link script and a root module to bring the program together. You will also have to learn about VROOM enough to be sure your modules are loading into Virtual memory under DOS, instead of precious program memory. The JORF Developer's kit costs $170 and is available only from The JORF Company. You also need the Borland Turbo C++ (about $105), Turbo C++ for Windows (about $105) or Borland C++ compiler for DOS and Windows (about $395). Programs compiled using the JORF Developer's kit may be distributed without paying any royalty to the JORF company. Please specify which compiler version you have, Borland has been playing with the object file format. We normally ship libraries for the current Borland versions. (3.1 as of January 1993). The JORF Manual (Shareware Disk Version) 14 Chapter Two Getting Started Getting Started This chapter introduces the JORF Interpreter, Debugger and Editor that you can use to edit JORF language programs. If you are an experienced programmer, you will probably just scan through here, and just hack your way through the menus. If you are new at programming, you might find this chapter covers the debugger a little too quickly. The JORF Programmer's Workbook goes into a more thorough examination of the Debugger, and shows you how to use each feature in a Step-By-Step fashion. There are three versions of the JORF Interpreter: JORF The regular interpreter for DOS PC computers You can run JORF version by changing to the JORF directory, and typing JORF: C>CD \JORF Change to the JORF directory C>JORF Type JORF JORF386 The JORF interpreter for 386 computers that takes advantage of high memory and 32-bit processing speed. You can run the JORF386 version by changing to the JORF directory, and typing JORF: C>CD \JORF Change to the JORF directory C>JORF386 Type JORF386 JORFWIN The Windows interpreter for running under MS-Windows 3.x From the Program Manager, add the JORFWIN Icon by selecting File - New. Select Program Item and press the OK Button. Fill out the screen as shown. Chapter One - Welcome to JORF 15 After pressing OK again, you should be able to see the JORFWIN Icon. After this, you can run the Windows version simply by clicking the JORFWIN Icon. Shareware Message I have been experimenting with a Shareware Opening screen. This screen features a short message about the shareware license for the JORF Interpreter. This screen is a simple reminder that the interpreter you are running is not registered, and that you must register it if you write new programs using it. The registered version does not display the message. The Editor and Debugger The Editor and Debugger screen is a programming tool to let you add, change and run JORF language programs in the interpreter. When you first start, the program displays a list of JORF file names for you to run. The JORF Manual (Shareware Disk Version) 16 All JORF screens comply to the Common User Access standard which uses the following keystrokes: Tab Key or Down Arrow Moves to next field or entry area Back-Tab Key or Up Arrow Moves to previous field or entry area Enter key Presses "Default" button Be very careful here not to press the Enter key at the end of a field. If this standard is not familiar to you, it may seem quite cumbersome. I personally think the Tab key is too small and far away to be used for such an essential task as ending a data entry prompt. But this standard is the emerging standard for PC programs, so if you grow accustom to it now, you will soon tire of the Non-standard programs you used before. The program I want you to run first is ASCII.J. This short program displays a table of ASCII characters on the screen. To select ASCII.J, Press the Tab key and arrow through the Files list so that ASCII.J is highlighted. Press Enter once to add ASCII.J to the program name field. Press Enter again to "Run" the program. Chapter Two - JORF Systems and Structures 17 When the ASCII.J program runs, it displays this following screen. There are two buttons, one to exit, and one that displays "Lower" if the upper ASCII characters are showing, and "Upper" if the lower ASCII characters are showing. Press the Enter key, Alt-U and Alt-L, or use your mouse to see this program run. Getting into the debugger a data entry screen To start the debugger, all you need to do is press Ctrl-Break. The break key is located on the top right corner of your keyboard. If you have an IBM-PC keyboard, the break key is labeled Scroll-Lock Break. If you have an IBM-AT keyboard, the key is labeled Pause Break. Programmers may note that Ctrl-C is a valid keystroke in JORF, and is not used as a break key. The JORF Manual (Shareware Disk Version) 18 When you start the debugger from a data entry screen, the debugger will start by displaying the method that created the screen. To debug through a button press routine you need to trace into that routine. The technique of tracing into button is covered in just a couple pages. In this example, you can see that the debugger is showing us ASCII:START method. This is the full program code for the start method of the ASCII.J program. All this code says to do is to create a windows with a Display routine and two buttons. There are also two markers around the first button, used to change the button depending on the display. (If the upper ASCII characters are showing, the button says "Lower" and if the lower ASCII characters are showing, the button says "Upper". The highlighted bar shows the currently executing line. If you have a color monitor, you will also see that the program text is highlighted in various colors. Syntax highlighting is useful to help show you syntax and spelling errors. Functions, methods, numbers, constants and punctuation are highlighted differently. Chapter Two - JORF Systems and Structures 19 Debugger Menu Options The main debugger screen has menu options for changing the program you are on, editing any method in the program, displaying variables, and tracing through the program. You can display the pull down menus by holding down the Alt-key and pressing the highlighted letter. If you have a mouse, you can use your mouse to make the selection. Debugger File Menu Open Press F4 to open and run a new program. This brings you right back to the screen you started with a selection of available programs to run. Use your mouse, tab or arrow keys to select a file name. Type in a path name if you wish to change directories. Run. Use the Run button to run the program. Edit. The edit button will return you to the debugger and editor, without editing the program. Re-Read. Sometimes you try to run a program, and nothing happens. This usually follows an incident where the program locked up. The reason this happens is that the .JRF file that contains the program is corrupted. This option erases and re-creates this file from the source file. If you have made changes to the The JORF Manual (Shareware Disk Version) 20 program, you will lose any changes that were not saved. Cancel. Pressing the Cancel button or the Escape key will return you to the main editing screen. Save When a program is run, the source is read into a .JRF file. This file contains the data in a special format that is much faster to access than the original source file. When you make editing changes to the program, these changes are made only to the .JRF file. To save these changes to the source file, you select the Save option from the menu. When the debugger saves a file it sets the methods in the file in a particular order: 1. Class Definitions alphabetically. 2. The "Start" Method 3. All methods alphabetically. In more complex applications, several source files may be open. In this case, when you select Save, the file that contains the currently displayed method is written to disk. Save As This option is the same as Save, but allows you to specify a new source file name. Go Press Alt-G at any time to stop editing and run your program. Program execution will continue from the currently executing line. Print Use this option to print the program source code. This option works by saving all current changes (Same as Save) and then printing the file from disk. Whenever you print from the JORF Interpreter, you will be given a standard printer menu. If the printer options on this menu do not conform to your printer, you can easily change them. To change the printer options, Run the SETUP.J program, or edit the JORF.INI file according to the directions in Appendix D. The JORF.INI file is where the default printer list is located, and it is really easy to set this up to suit your system. Restart This option restarts your program from the beginning. Use it whenever you are changing method names or make extensive changes in the source code. Chapter Two - JORF Systems and Structures 21 Re-Read If your program locks up in the interpreter, you will probably need this option. Use it if you try to "Run" or "Edit" a program and you get a blank screen instead. If the program were invalid, you would be told so. But if the program file exists in a corrupted state, the Start method cannot be found, and the Debugger will show only a blank screen. This option erases the corrupted .JRF file and re-reads the source program to re-create it. Changes made after your last Save will be lost. I am constantly working to a) make JORF so it doesn't lock up and b) make it so it leaves the file uncorrupted. However, until I succeed you will have to use "Re-Read". Exit Press Alt-X at any time to exit from the Debugger. There is a polite "Last Chance" box before you leave. If you press OK you will be returned to the DOS prompt or to the Windows Program manager. Debugger Edit Dialog Box When you select Edit from the debugger screen, you will see the following dialog box. This box allows you to select Methods by Class, and enables you to Add, Change and Delete the methods. Methods and Classes The JORF language is Object Oriented. In JORF, all methods (routines) must be prefixed by a class name. Methods are grouped by class, and on this screen you must select class first, then method. This system of naming methods does not make much sense with small programs like ASCII.J. In fact, the whole system was only invented recently, after two decades of computer programming without classes. In large programs, however, the practice of defining classes and keeping methods tightly bound to those classes has proven to be very efficient. Generally, you should name a class by the type of data being operated on, and by the general function of the class. Methods can be any name you want. A good class has under 30 methods. A good method has under 30 lines of code. A good method should do just one task, not three or four. The size of classes and methods is often specified as "Granularity" and good granularity comes from succinct classes and methods. The JORF Manual (Shareware Disk Version) 22 Edit When you have specified a Method name and Class name, press the Edit button to edit the method. Cancel This returns you back from whence you came. If it did anything else, the cancel button would not make much sense, would it? Add Type in a new method or Class name and press Add to create that method. There are two ways of creating a new method. One is to use this button to "Add" it, the other is to use "Copy" to copy an existing method. When you add a method, the editor creates the method beginning and end for you. MyMethod:Start | Return It does this only to avoid "Blank screen syndrome" and give you a place to start typing. The comment line in the center is where you can write a comment about the purpose of the method, and also type in the lines of program code that will comprise the method. Chapter Two - JORF Systems and Structures 23 Delete To truly get rid of a method, you can select Delete. You should be sure to save your program soon after, so your delete is saved to the source file. If you use an outside editor: You will quickly learn that the JORF interpreter re-reads your program whenever you make a change. When re-reading, however, your changes are merged with the current program routines in the .JRF file. That means when you delete a method in the source file, it will still remain in the .JRF file. If you delete a method in the source file, you should also delete the .JRF file so that the .JRF file is re-created. Copy Instead of Adding a blank method, you can copy an existing method and edit from your copy. This is especially useful for keystroke handling methods where you may want to define several keys to do the same thing. The JORF Manual (Shareware Disk Version) 24 Debugger Show Menu The Show menu groups together four options. One to view the other screen, and three to show you what the interpreter sees in your program. Other Screen Select this option or press Alt-O to see your program screen. If you are running in DOS, your program screen is completely hidden by the debugger screen. This option allows you to view your program. If you are running in Windows and you have a Super VGA monitor, you may be able to move your program screen to one side so you can view it at the same time as the editor screen. If not, you can use this option to show your screen. Show Stack When you are running a method that is called by a method this option shows you all the methods that are being called in order. Chapter Two - JORF Systems and Structures 25 In our little ASCII.J example this is hardly useful, but in a "real" program you may be nested ten methods deep, and it is often useful to see exactly which methods were called to get where you are now. Show Variables Use this option to see your currently active variables. You will see a short screen that shows: 1) Parameter values for the current method 2) New variables in the current method 3) The Mem:Ptr global variable pointer 4) The Win:Ptr for the current screen If any value is a Structure, you can highlight it and press Enter to see the values of that structure. The same goes for Mem:Ptr and Win:Ptr. Add Watch Select this option to add a new Watch variable to the screen as you are tracing. This option is also available from the Watches menu (covered in just a couple pages) and so turn there for more information. Debugger Menu The debugger menu gives you the options to trace, rewind, and mark break points in a method. The JORF debugger, like most Object Oriented debuggers, allows you to change currently executing programs without breaking execution. When you finish your change, you simply continue the current run of the program. The JORF Manual (Shareware Disk Version) 26 Once you get used to the capability of changing a program on-the-fly, you may find that static program debuggers are much less convenient. Programmers will note two pleasant additions to the usual trace functions. The Rewind function can move the program pointer back up a routine. You can use this option to back up over a changed line of code, and then re-execute it to set a variable to a new value. The Finish function executes the program to the end of the current method, and begins tracing again on the next line. Use this when you accidentally trace into a method. By finishing, you will be right back to the spot you would have been if you traced over the method. Go Press Alt-G at any time to stop editing and run your program. Program execution will continue from the currently executing line. Do Line Does the current line and stop at the next line. If this line calls another method, switches to show the new method and stops on the first executing line of that method. This option differs from Next Line because it traces into method calls. Next Line Runs the program until the next line. This option traces over any method calls in the highlighted line. Chapter Two - JORF Systems and Structures 27 Rewind Pressing Alt-R will rewind the program pointer back by one line. You can use this to rewind back over a changed line in the program. There is an important limitation to the rewind function, you cannot rewind out of an indented control function, like If or While. As the screen suggests, you need to move forward until you are out of the indented section, then rewind to the line above the indented section. The Rewind function is not the same as reverse execution. Program statements are not "Undone", and counters and accumulators will not be unset by rewinding. The purpose of this command is not to undo operation, but merely to allow you to fix a bug and re- execute a section of a method with the fixed code. Neither Mr. Borland nor Mr. Microsoft can do this either. Perhaps they should, since it makes it so easy to debug code to be able to change it and re-execute the new code with just a couple keystrokes. Finish Method Finishes the current method, and stops at the next program line. If you trace into a method using Do Line, you can use this option to finish the method. The program control will stop as if you traced over the method using Next Line. Neither Mr. Borland nor Mr. Microsoft and do this simple but useful function! Trace Forward Press Alt-T at any time to begin automatic trace mode. You can use this option to watch your program run. As it is running you can change the speed at which lines are executed: Press F to go faster Press S to go more slowly Press any other key to end automatic trace mode. This mode is useful to get an overview of how a program runs, and to see which methods are used for a given function. The JORF Manual (Shareware Disk Version) 28 Toggle Break Point Use this option to mark a line as a break point. When a line is marked as a break point, program execution will stop just before that line is executed, as if you pressed Ctrl-Break exactly at that spot. In the debugger, you can have up to ten break points. Usually, having more than 2 active at once is pretty confusing. This option is a toggle, which means that executing it once sets the break point on, and a second time sets the break point off. Debugger Watch Menu The JORF debugger has a special feature called "AutoWatches". These are special watch variables that are changed and displayed according to the executed program code. One autowatch will always show the value of the last assigned variable. The other, shows whether the current conditional statement (If or While) is true. You can also set normal watch variables. These are values that re-display with each program line so you can examine the status of the program. Add Watch Use this to add a watch variable. The screen adjusts to show up to five watch variables at one time. However, since each watch variable must be recalculated for every program line, the more watches you have, the slower the screen will display. Delete Watches This option will delete all program watch variables except autowatches. This will make your screen clean and faster to redisplay. Autowatch On When autowatch is on, the first watch variable will be automatically set to be the current conditional value and the second watch will be the last assigned value. Chapter Two - JORF Systems and Structures 29 This Conditional is the result of the current If or While statement. In the example above, the if statement is testing ((Char%8)==7). (The % function is read as "Mod", short for modulus, and is used to test the remainder of integer division. In this case, we are testing to see whether the value of Char divided by eight leaves a remainder of seven.) You can see in the screen above that the result is (Null) so the executing line moved to the Else clause. The second watch was set in the For statement to the variable Char which has a value of 128. The assignment watch is set whenever a variable is assigned using the equals (=) sign. Autowatch Off When I created the Autowatches, I was heartbroken to find that they are barely usable on an XT style computer. This style computer is so slow, that testing and displaying the Autowatch variables is just painful to watch. If you have a slow computer, or feel that Autowatches are not very useful, you can turn them off. Turning off autowatches does not affect your defined watch variables. Debugger Help The Help options on the debugger screen give access to keyboard references and to the context sensitive help system. Editing Keys Select this option to get a list of editing keys. JORF uses old Wordstar control keys, and also IBM keyboard arrow and home keys. Debugger Keys Select this option to get a list of debugger Alt keystrokes. JORF Help Select this option, or press F1 to use the JORF context sensitive help system. This system uses a file called HELP.JRF which needs to be on the current directory, your start up directory, or the \JORF directory of your current disk drive. You can use the context sensitive help by highlighting program key words. If the word at the cursor position is a listed keyword, you will see the help screen appropriate to that word. For instance, place the cursor on Win:Add and press F1 to see the help screen on the Win:Add function. The JORF Manual (Shareware Disk Version) 30 Chapter Three JORF Math JORF Math Many Object Oriented Languages treat math operators as Method Calls. This is really cute when you use "+" to concatenate a structures, and "=" to assign them. However, this is not easy to implement and leads to a host of problems. For instance, to implement "+", you have to create a language syntax between operators. This is the reason Smalltalk program lines are scrambled, and C++ has an involved "Friend" system. When this is all done, it is hard to figure out how to handle a "+" between different types of objects. You can create a method for Dog + Dog, but what about Dog + Penguin? Is that a Doguin or a Pog? And you have slowed down all regular math processing just to implement this difficult to use feature. For about two months, JORF used this math technique. But there were so many kludges to make the syntax work, keep order of operations, and enhance speed that the entire system was not simple and intuitive. So, I dumped the concept and went to a stack oriented math system like that in BASIC, PASCAL and C language. The JORF system solves math operations automatically as the programming line is executed. The line is executed from Right to Left (the opposite of how you read). As each Method or Function is called, any adjacent Math expressions are completed. Win:Add (To:Caps(Title), LastRow+2, LastColumn+5, 0, 0, Here) JORF first performs Here. Then it reads the line back to the To:Caps function. Before performing it, it evaluates the math expressions LastRow+2 and LastColumn+5 even though they are unrelated to To:Caps. Until JORF calls a function it doesn't know how many parameters that function takes. To:Caps Title will return the contents of Title capitalized. Finally, the Win:Add function is called. Chapter Two - JORF Systems and Structures 31 Order of Operations Mathematic operations are handled in the following order. This is essentially the same as the C language: -> Pointer References [] Array References - ! ~ ++ -- Unary operations * / % Multiplication + - Addition < > <= >= Evaluation == != Equality && ?? And Or Logical AND and OR = Assignment The JORF Manual (Shareware Disk Version) 32 Addition (+) Symbol + Purpose Add numbers, concatenate strings. Notes The plus sign adds numbers if both sides are numbers, and if one or both operands are strings then they are concatenated. To "Add" text you must use the Text:Add function. To "Add" elements of structures, use the strange and obscure Jorf:Move function. Examples 1 + 5 = 6 2 + 78.8 = 80.8 5 + "A" = 5A To:Str(3) + To:Str(3) = "33" 65535 + 1 = 65536 Chapter Three - JORF Math 33 Assignment (=) Symbol = Purpose Assign a value to a variable. Notes Assigns the value of the right operand to the left operand. Usually, only the value is assigned and not the class. If the destination has no declared class, and the source does, the destination will take on both the class and value of the source. Assignment may be made to structure elements and arrays. You cannot assign "To" a constant value. Single data items are assigned by value, but structures and text are assigned by reference. Examples A = 6 | A is now equal to 6 Addr->Addr1 = "2343 N. Main Street" | Sets the Addr1 element of Addr Addr[4] = Addr | Sets the fourth array element "Three" = 2 | Nonsense! Three is a constant Three = 2 | If three is a variable, O.K. The JORF Manual (Shareware Disk Version) 34 Decrement (--) Symbol -- Purpose Subtract one from a number. Notes It is a common operation in programs to have loop counters that count up by one, or down by one. These are so common in assembler that there are real assembly instructions to do just these operations. I'm afraid the JORF Translate and compile system is not efficient enough to compile to the assembler decrement instruction, but it is still a good concept and a logical part of the language. The Decrement operator must be IN FRONT of the operand, and not behind as allowed in the C language. This operator simply subtracts one from the operand. Examples Num = Num - 1 | Normal Decrementing --Num | But -- is shorter, easier. Decr:Start New Num Win:Add ("Showing Decrement", 4,4,12,30, Here) Num = 10 While (Num > 0) | Loop until zero Str:PutLine ("Number = " + Num) | Put 'Number = 10' --Num Str:PutLine ("Done") Win:Pause Return Chapter Three - JORF Math 35 Division (/) Symbol / Purpose Divide two numbers. Notes You remember how to do long division don't you? Well the computer does, and this is what you need to do it. The JORF language is unusual in that it does the type conversions necessary when division yields a fractional result. Most languages truncate the result of integer division. You should be especially careful when using division to calculate screen position, because the fractional result is not the same as the truncated result: Move:To (2, (30-Str:Len "Hi Jo")/2) becomes Move:To (2, (30-5)/2) becomes Move:To (2, 25/2) becomes Move:To (2, 12.5) becomes Move:To (2, 13) Not Move:To (2, 12) as it would in C or Pascal. Examples 12 / 2 = 5 60000 / 100 = 600 12.5 / .5 = 25 The JORF Manual (Shareware Disk Version) 36 Equality (= or ==) Symbol = or == Purpose Check to see if two numbers, strings or structures are equal. Checks text only for the current line, not the whole text. Notes Returns TRUE if the left operand is equal to the right operand. When I was a BASIC programmer, I could never discern the difference between checking for Equality, and assigning a value. To me, the both were "Equals". The C language not only warns of this ambiguity, but does not work correctly at all if you ignore the warnings. It does exactly what you tell it, assigns or checks, and not what you want it to do. So JORF treads the line. For BASIC programmers, the = sign can be used for both equality checking and also for assignment. For C programmers, use == for equality, and = for assignment. In all examples, I will use == because it is more robust. Examples A = 1 | Assignment of 1 to A If (A == 2) | Check equality, is A equal to 2? Str:PutLine ("A is 2") Else Str:PutLine ("A is Not 2") | Will print this line Chapter Three - JORF Math 37 Increment (++) Symbol ++ Purpose Add one to a counter. Notes It is a common operation in programs to have loop counters that count up by one, or down by one. These are so common in assembler that there are real assembly instructions to do just these operations. I'm afraid the JORF Translate and compile system is not efficient enough to compile to the assembler decrement instruction, but it is still a good concept and a logical part of the language. The Increment operator must be IN FRONT of the operand, and not behind as allowed in the C language. This operator simply adds one to operand. Examples Num = Num + 1 | Normal Decrementing ++Num | But -- is shorter, easier. Incr:Start New Num Win:Add ("Showing Increment", 4,4,12,30, Here) Num = 0 While (Num < 10) | Loop until zero ++Num Str:PutLine ("Number = "+Num) | Put 'Number = 1' Str:PutLine ("Done") Win:Pause Return The JORF Manual (Shareware Disk Version) 38 Inequality (!= or <>) Symbol != or <> Purpose Test to see if two numbers are not equal. Notes I could never decide whether I like the BASIC <> or the C language != better. I know that I hate the Clipper ambiguity where they are slightly different. So, in JORF they are exactly the same, but you can use either symbol. Since learning C brings higher salaries than learning BASIC, I usually use the != (! means Not, = Means Equals; Not-Equals) in my examples. Examples A = 1 | Assignment of 1 to A If (A != 2) | Check equality, is A not equal to 2? Str:PutLine ("A is not 2") | Will print this line Chapter Three - JORF Math 39 Greater Than (>) Symbol > Purpose Test to see if the first operand is greater than the second. Notes Returns True if the First operand is greater than the second. Type conversion is the same as assignment. Numbers are compared numerically, and strings are compared as strings. String comparison is not case sensitive. Examples 1 > 5 False "B" > "A" True "B" > "a" True "B" > 1 True because 1 is converted to "1" "33" > 111 True because "33" is converted to 33 The JORF Manual (Shareware Disk Version) 40 Greater Than or Equal To (>=) Symbol >= Purpose Test to see if the first operand is greater or equal to the second. Notes Returns True if the First operand is greater than or equal to the second. Type conversion is the same as assignment. Numbers are compared numerically, and strings are compared as strings. String comparison is not case sensitive. Reversing the symbols to be => has no meaning in JORF. Examples 1 >= 5 False "B" >= "A" True "B" >= "b" True "B" >= 1 True because 1 is converted to "1" "33" >= 33 True because "33" is converted to 33 Chapter Three - JORF Math 41 Less Than (<) Symbol < Purpose Test to see if the first operand is less than the second. Notes Returns True if the First operand is less than the second. Type conversion is the same as assignment. Numbers are compared numerically, and strings are compared as strings. String comparison is not case sensitive. Examples 1 < 5 True "B" < "A" False "B" < "a" False "B" < 1 False because 1 is converted to "1" "33" < 111 False because "33" is converted to 33 The JORF Manual (Shareware Disk Version) 42 Less Than or Equal To (<=) Symbol <= Purpose Test to see if the first operand is less than or equal to the second. Notes Returns True if the First operand is less than or equal to the second. Type conversion is the same as assignment. Numbers are compared numerically, and strings are compared as strings. String comparison is not case sensitive. Reversing the symbol has no meaning in the current version. There is no =< operation. Examples 1 <= 5 True "B" <= "A" False "B" <= "b" True "B" <= 1 False because 1 is converted to "1" "33" > 111 False because "33" is converted to 33 Chapter Three - JORF Math 43 Logical AND (&&) Symbol && or And Purpose Test whether two logical values are both True. Notes An If statement uses the Logical And to make two tests at once. Each operand may be a test for equality, or may be a test for null. In JORF, Null, FALSE and Zero are exactly the same. The word "And" may now be used as a synonym for &&. It looks better, but gives And a funny status as kinda-a- key-word. The AND statement always evaluates both sides, without shortcuts as in the C language. Examples AndTest:Start New A, B A = 4 B = 2 Win:Add ("And Test", 0, 0, 10, 60, Here) If (A And B) Str:PutLine ("Test 1, Both A and B have values") If (A & B) Str:PutLine ("Test 2, Logical And, Bitwise & are different") If (A < 5 And B > 4) Str:PutLine ("Test 3, Use And to connect compound tests") Win:Pause Return The JORF Manual (Shareware Disk Version) 44 Logical NEGATION (!) Symbol ! or Not Purpose Test whether a logical values is not true. Notes You can reverse a logical statement using the logical NOT. It is usually more desirable to reverse the logical test, especially if mixing Not, And and OR. Returns true if the operand is FALSE, Null or Zero. The word "Not" may be used as a synonym for !. Examples NotTest:Start New A, B A = 4 B = 0 Win:Add ("Not Test", 0, 0, 10, 60, Here) If (Not A) Str:PutLine ("Test 1, A is not 'True'") If (Not A And Not B) Str:PutLine ("Test 2, Not can be ambiguous") If Not (A < 5 And B < 5) Str:PutLine ("Test 3, Use Not to reverse a test") Win:Pause Return Chapter Three - JORF Math 45 Logical OR (??) Symbol ?? or Or Purpose Test whether one or the other of two logical values are True. Notes An If statement uses the Logical Or to make two tests at once. Each operand may be a test for equality, or may be a test for null. In JORF, Null, FALSE and Zero are exactly the same. The word "Or" may now be used as a synonym for ??. You should be careful mixing And and Or in the same expression. Doing so can make the statement ambiguous. To avoid this, use parentheses so that each test contains just one And or one Or. Examples OrTest:Start New A, B, C A = 4 B = 0 C = 6 Win:Add ("Or Test", 0, 0, 10, 60, Here) If (A Or B) Str:PutLine ("Test 1, One of A or B has a values") If (A Or B And C) Str:PutLine ("Test 2, Mixing can be ambiguous") If ((A Or B) And C) Str:PutLine ("Test 3, But Parentheses makes it clear") Win:Pause Return The JORF Manual (Shareware Disk Version) 46 Modulus (%) Symbol % Purpose Return the Integer remainder of Integer division. Notes The Modulus operator is used in conjunction with counters to create cycles. A cycle is a set of values that loop. To turn a numeric counter into the cycle 0, 1, 2, 3, 4, 0, 1, 2, 3, 4, 0, 1, 2, 3, 4 you use the modulus of 5. 0 % 5 = 0 7 % 5 = 2 14 % 5 = 4 1 % 5 = 1 8 % 5 = 3 15 % 5 = 0 2 % 5 = 2 9 % 5 = 4 16 % 5 = 1 3 % 5 = 3 10 % 5 = 0 17 % 5 = 2 4 % 5 = 4 11 % 5 = 1 18 % 5 = 3 5 % 5 = 0 12 % 5 = 2 19 % 5 = 4 6 % 5 = 1 13 % 5 = 3 20 % 5 = 0 Examples My favorite is the use of modulus in the ASCII.J file. This program uses modulus start a new line every 16th character. Ascii:Show(Base) New (Char) Win:Attr("Lo") Move:To(1,1) | Display 128 Ascii characters For (Char = Base Thru 127+Base) Str:Put(To:Str(Char,"000 ")) Char:Put(Char) If ((Char %8)==7) Str:PutLine() Else Str:Put(" ") Win:Attr("No") Return (Ok) Chapter Three - JORF Math 47 Multiplication (*) Symbol * Purpose Multiply numbers. Notes Two numbers are multiplied. If the numbers are integers, and the result is very large, it may be converted to floating point. Multiplication of floating point numbers can result in an integer result. Examples 20 * 55.5 = 1110 22.4 * 4 = 89.2 The JORF Manual (Shareware Disk Version) 48 Negation (-) Symbol - Purpose Negates a number. Notes Unary negation is done by preceding any expression with a minus sign. This symbol negates the value. Parentheses are recommended to avoid ambiguity with the subtraction operation. The most common use is to pass a negative number to a function. Negative numbers. Examples The Windows program displays a few windows. Positive Row and Column positions are offsets from the top left corner. Negative Row and Column positions are offsets from the bottom right corner. No matter how big or small the screen, these boxes will be placed in the same relative positions. Windows:Start Win:Add ("Big", 2, 2, -2, -2) Win:Add ("Top Right", 3, 3, 3, 15) Win:Add ("Bottom Right",-3, 3, 3, 15) Win:Add ("Bottom Left", -3, -3, 3, 15) Win:Add ("Top Left", 3, -3, 3, 15) Win:Add ("Tall", 3, 45, -4, 10) Win:Add ("Wide", 10, 3, 3, -4) Win:Pause Return Ok Chapter Three - JORF Math 49 Subtraction (-) Symbol - Purpose Subtract two numbers. Notes The plus sign adds numbers if both sides are numbers, and if one or both operands are strings then they are concatenated. Although it would make sense, multiple line Texts are not concatenated, and are handle only as the current line of text. Also structures and arrays are not concatenated. Examples 1 - 5 = -4 78.8 - 2 = 76.8 65536 - 1 = 65535 The JORF Manual (Shareware Disk Version) 50 Chapter Four The Window Manager The Window Manager The JORF Window Management system handles pull down and pop up menus, hypertext prompts, radio buttons, check boxes, and data entry fields. Cursor control between fields and mouse control is handled automatically. The JORF window management system is handled entirely within the Win:Add and Win:Chg functions. Both functions can be followed by a window definition section of commands. Each command begins with a command verb, followed by a colon, followed by a quoted prompt. The commands are defined in detail below. Although command verbs look like the class definition of a method call, they are not calls to JORF language methods. The use of the colon in the key words is simply for consistency with the "look" of JORF language programs, and should not be mistaken for class oriented functions. A "Prototype" window is shown below: Event:Add ("EditKey") Win:Add ("Title", Row, Col, Len, Wid, Level) Command:"Prompt", Option:"value", Option:"value" Option:"More Values can be Indented" Option:"For as many lines as necessary" Command:"Prompt", Option:"value", Option:"value" Command:"Prompt", Option:"value", Option:"value" You can also place a text paragraph at the bottom. The system looks for the keyword and colon (:) character and if they are absent will print the rest of the indented screen definition as a text paragraph. You can embed commands within text by enclosing some commands in {Command:"Curly brackets, Option:"value"}. This can be used for hypertext prompts and buttons that are embedded in the text. Return Chapter Three - JORF Math 51 You can see in the above example, there are a number of complex rules for declaring comments. Indented Text is subordinate to the Win:Add command. There can be additional indentations, but the window definition ends at the end of the function or the next unindented command. The Command section is always the first section in a window definition. It continues as long as there is a Colon in the first expression of the line. If the expression is not a valid command word an error is displayed. The Text Section begins on the first line where there is No Colon. Some commands, notably the Prompt command that is used for hypertext, can be included in the text section if it is surrounded by Curly Brackets. Prompts and commands are handled as JORF language values. They are quoted if they are strings, but not if they are numeric. If they are unquoted, they are assumed to be variable values and must be valid parameters or new variables in the method that creates the window. The sequence of fields during data entry follows the sequence the fields are declared. The following is a summary of command values: Array:"" An array pick list Button:"Prompt" A button ChBox:"Prompt" A check box Group:"Prompt" A group box (single line box) Input:"Prompt" A data entry field List:"" A record pick list Marker:"Markername" A marker section for Win:Chg Menu:"Prompt" A menu bar option MLine:"Prompt" A menu line option Prompt:"Prompt" A hypertext prompt Radio:"Prompt" A radio button String:"DisplayString" A string (no data entry) Text:"" A data entry field Keystroke handling is done by a combination of event system and automatic commands. Every keystroke is first passed through the event handling system. There is an event class called EditKey built into the interpreter that is the default key handler. For your window to operate properly, you must set the Editkey class using the Event:Add command. Event:Add ("EditKey") The JORF Manual (Shareware Disk Version) 52 This handler takes care of all letters and numbers, handles WordStar style control key functions, handles WordPerfect style Home, End and Page keys, and handles Arrow Keys. You can create a substitute handler for some or all keys. Also, you can layer another handler on top of the existing handler. This allows you to change defaults for a few keys without having to redefine an entirely new handler. You might make a handler that makes the F7 key exit the screen, instead of Alt_F4. To use it you simply create a new class and define the routines. MyKeys:F7_Key If (Editkey:FinishEdit) | If OK to finish editing Jorf:Exit | Exit the program Return (Ok) | Otherwise, return OK MyKeys:Alt_F4_Key Return ('Alt_F4_Key') | Block Alt-F4 from further processing The first method does what Alt-F4 would normally do, execute the FinishEdit function to save the data and then exit. The second method simply blocks the F10 key from further processing. When a keystroke method is processed, the return value is critical in specifying further processing. Possible return values are: Null Keystroke is not processed - continue checking event stack Ok Keystroke is processed - processing is complete The Keystroke Keystroke is processed - and not changed Another Keystroke Keystroke is processed - and changed to this keystroke. Used to change key combination into other printable characters. The above definition is a complete event class that redefines to keystrokes. To use this class, layered above the normal Editkey class, means you use the Event:Add function twice: Event:Add | A Null event blocks lower keystroke Event:Add ("EditKey") | Normal Key Processing Event:Add ("MyKey") | Substitute for F7, F10 Win:Add ("Title", . . .) ... Return The event layering system enables you to trap and change any keystroke. The layering allows you to add new functionality to any key, above what is already defined. Chapter Four - The Window Manager 53 The complete EditKey class is given in source code form with the JORF Developer's Kit. Having this code gives you the source code you need to create your own word processing system. This source code is written in the JORF language, and is translated and compiled to the C language. Windows Function keys Handling of keystrokes between fields conforms basically to the CUA standard supported by Microsoft Windows. That means there are pre-defined keys that you should use in your programs. Here is a list of keys built into JORF. Key Function Who does it F1 Help You do this. F3 "Save Text" Editkey Tab Next Input or Button Automatic Back-Tab Previ Input or Button Automatic Alt-Keys Jump to menu/button Automatic Arrow Keys Up and Down Automatic Enter Key on a Button Executes Button Automatic Enter Key on a field Goes to next field You do this. Space bar on radio Toggles button Automatic Escape Key Exits Window Automatic Alt-X Exits Application You do this. Alt-F4 Key Exits Application You do this. The F3 key is defined as a "Save" key in the Editkey processor routine. It is automatically in effect when text is edited. You must be sure to define F1 and Alt-F4 in Windows programs. These keystrokes are so standard that you should always set them up. DOS Programs also have a standard of using F1 as the help key. DOS programs sometimes exit with Alt-Q instead of Alt-X, but one of these should always be defined. The CUA standard says that when you press the Enter key, the currently highlighted button is executed. Before buttons were common in DOS programs, the enter key was commonly used to end data entry in one field and move to the next field. You can easily change JORF programs to support the DOS-like action, even though your program will be in flagrant violation of CUA standards. Just use the following routine to change the keystroke: MyProg:Enter_Key Return ("Tab_Key") The JORF Manual (Shareware Disk Version) 54 Windows Alt Keys You can include an ampersand (&) character within any prompt to create an Alt key accelerator. In the JORF language, these are handled automatically by the window management system. Under DOS, Alt keys are highlighted, and in Windows programs they are underlined in menus, and highlighted when in screens. Windows programmers may note that under windows, JORF uses the Windows menu handling system. Windows data input fields were not amenable to handling by JORF, so JORF data entry fields are highlighted differently and handled differently than true Windows input fields. One simple advantage of the JORF fields is that they are smaller, so you can fit up to 25 lines of prompts per window, instead of just 15 lines of prompts on a normal Windows screen. Radio Buttons and Check boxes are a hybrid, where the buttons are defined as child windows, but the prompts and Alt keys are handled entirely by JORF and not by Windows. In addition to highlighted prompts, any menu item can be run by defining a Hotkey definition. (This is an "Accelerator" in Windows lingo". Just follow the menu definition by the word Hotkey, a colon, and the keystroke to be used. Most of the time you also want to indicate the key within the menu prompt. To define an accelerator in a menu, you must have at least two spaces between the prompt and the notation for the accelerator and you should right align your accelerator prompts by hand. See the sample program MAILLIST.J printed below for an example of Hotkey accelerators in use. Alt Keys within Data Entry Windows You can highlight Alt key prompts for every data entry field, group box, or radio button on a screen. As a person who has designed such screens for almost 10 years, this ability is provides greatest ease of access I have ever experienced. Any screen that grows larger than 8 prompts gets to be a pain to change. Most programs start your cursor on the top, and you have to arrow down through the fields to get to the one you want to change. In the last two years, I have done some contracted modifications to a program that has more than 18 fields on the first screen, and the most common to change are often the last seven. Every time an operator needs to change this one field, they must press the down arrow at least 10 times! If you use your Alt keys and group boxes, you can make this cursor movement unnecessary. Pressing Alt and the highlighted letter of an input prompt will bring you immediately to that prompt. If there are too many prompts, group similar ones using Chapter Four - The Window Manager 55 group boxes that themselves have a highlighted letter. You can see an example of that in the contact manager program CONTACT.J Windows Settings When a window is created using the Win:Add command, a new Win:Ptr structure is created. This structure can have many elements that can be set using the same syntax as the commands. Simply by declaring a windowstructure label followed by a colon followed by a value, will set that value within the window before any display takes place. In this simple example, (HAPPY.J) we can create a window with a yellow background and a message that says "I'm Happy" Happy:Start Win:Add Attr:"Green/Yellow" Msg:"I'm Happy" Button:"&Ok" Row:6 How are we doing. Return (Ok) Each element in the window structure has only one value, as opposed to a Window Command which has values for row, column, field name, and other routines. The most common elements set in this fashion are Window Before, InpBefore and Display values, that define methods to execute before the window is displayed, before each input is entered, and before the window is redisplayed respectively. The complete list of values is as follows: Type Changes the color mode for the window. You can set up new color sequences in the JORF.INI file, and then specify them here. That way, each type of window in your application has its own colors. Changes the default colors and line style Magic Setting Magic to False will keep the window from trying to interpret magic spots (fields surrounded by {curly brackets}). Normally Magic is TRUE, and any bracket expression is interpreted. Attr Setting Attr changes the starting attribute for text display in the window. The value can be any legal value documented in the Win:Attr function. FLRCO Setting FLRCO changes the current wrap mode. The default mode is "L" for left justified text. The JORF Manual (Shareware Disk Version) 56 Before Setting Before specifies a method to be executed before any data entry takes place on the window. It can be used to display additional information for the operator, or to test input or display parameters. If the Before method returns FALSE, the window entry is ignored. Display Setting Display is similar to setting Before. The difference is that the Before method executes before any part of the window is displayed, but the Display routine executes after the window box is showing. The Display routine can then add visual elements to the window that are not included in buttons and fields that make up the rest of the window definition. After Setting After specifies a method to be executed when the operator attempts to exit the window using the Escape key or the window close button. On text entry windows, it is common to specify a method to ask whether to save the changed document before exiting the window. If the After method returns False, then the window remains displayed as if the operator did not request an exit. InpBefore InpAfter InpBefore and InpAfter may be used to specify methods that must be run before and after every input field (including buttons and check boxes) in the window. These methods are commonly used to lock the record, as well as qualify the operator rights to change the field. If the Before method returns False, the operator will not be able to change the field. If the After method returns False, the operator will not be able to move to another field (presumably until the operator corrects the field value.) Chapter Four - The Window Manager 57 Array Command Array:"" Purpose A pick list of array elements. Options Row:10 Set Row Col:10 Set Column Wid:10 Set Width of List Len:3 Set Length of List After:"Expr" Expression is executed after list.. Before:"Expr" Expression is executed. If false, the operator cannot pick from list. Field:"Fldname" Command to execute for Next Record Choice:"Field" Command to execute for Previous Record Defaults Row One row below previous command. If the previous command is a Group Box, then Row, Col, Wid and Len default to the inside dimensions of the box. Col Same column as previous command. Wid 30 Len 1 Highlight Arrays are highlighted like menus. No cursor is displayed, even when the array has focus. See Also List. Notes This command works like List, but operates only on arrays and is much faster. The fact that it works on arrays limits the size of the data you can edit, but this is a good vehicle for pick lists up to a thousand elements. The JORF Manual (Shareware Disk Version) 58 Example The DirList.J program creates a "Dialog Directory list" and returns the selected file. Here is the DirList by itself. The TextEdit.J program uses it to select a file to edit. This program is compiled into the interpreter as the DirList:GetFile() function. Class:DirList | Class Definition Name | File Name Path | File Path WildCard | Wildcard for directory ExclusionList | Extension Exclusion List FileArray | Array of files on this path DirArray | Array of other paths DirList:Start | FOR TESTING: Start routine New (FileName) FileName = DirList:GetFile("*.*",Null) Msg:Add File name is {FileName} Return (Ok) DirList:Cancel(List) | Routine to Cancel data entry List->Name=Null | Signal that we canceled Return(Null) | Returning Null will finish input DirList:Done(List,Name) | Routine to finish data entry If (Str:In(List->Name,"*") Or Str:In(List->Name,"?")) List->WildCard = List->Name List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) Kbd:Put("Home_Key") | Stuff home key Win:Dsp | Redisplay (including arrays) Return (Ok) If (List->Name==Null) | If name is still null display message Msg:Add Please select a file name or "Cancel". Return (Ok) | Returning Ok will continue input Return (Null) | Returning Null will finish input DirList:FileArray(WildCard,Exclusionlist) | Read a file array New (Array) If (WildCard!="SUBDIR") Win:Add ('Reading') Reading directory Array = Arr:Dir (WildCard, ExclusionList, 12) Return (Array) DirList:GetFile(WildCard,ExclusionList) New (OrigPath, DirList:List, DirChoice, FileChoice) Chapter Four - The Window Manager 59 | Initalize values OrigPath = File:ChDir() List->Path = OrigPath List->WildCard = WildCard List->ExclusionList = Exclusionlist List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) List->DirArray = DirList:FileArray("SUBDIR") Event:Add(Null) | Block prior keystroke events Win:Add ("Get File Name", 0, 0, 10, 56, Here) | Input File Name Input:"File&name: ", Wid:24, Row:2, Col:3, Field:"List->Name" | Files array with a group box around Group:"&Files", Row:6, Col:2, Wid:16, Len:10 Array:"", Field:"List->FileArray", Choice:"FileChoice", Action:"DirList:NewName(List,List->FileArray[FileChoice])" | Directories array with a group box around Group:"&Directories", Row:6, Col:22, Wid:16, Len:10 Array:"", Field:"List->DirArray", Choice:"DirChoice" Action:"DirList:NewDir(List,List->DirArray[DirChoice])" | Input File Path Input:"Directory: ", Wid:24, Row:4, Col:3, Field:"List->Path" After:"DirList:NewDir(List,List->Path)" | Two buttons Button:" &Ok ", Row:1, Col:42, Wid:14 Action:"DirList:Done(List,List->FileArray[FileChoice])" Button:" &Cancel ", Row:4, Col:42, Wid:14 Action:"DirList:Cancel(List)" If (File:ChDir(OrigPath)) If (List->Name) If (Str:At(List->Path,Str:Len(List->Path),1)=='\') Return (List->Path+List->Name) Return (List->Path+'\'+List->Name) Return (Null) DirList:NewDir(List,Path) | Routine to set a new path If (File:Chdir(Path)) | Change to the new path List->Path = File:ChDir() | Reset path name List->Name = Null | Set file name to null | Re-read file array List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) | Re-Read directory array - special argument "SUBDIR" does this List->DirArray = DirList:FileArray("SUBDIR") Win:Dsp | Redisplay Window The JORF Manual (Shareware Disk Version) 60 Return(Ok) | Returning Ok continues input DirList:NewName(List,Name) | Routine to set a new name List->Name = Word:At(Name,1) | Set the name (Easy!) Win:Dsp | Redisplay the screen Kbd:Put("Home_Key") | And go back to file name Return(Ok) | Returning OK will continue input Chapter Four - The Window Manager 61 ChBox Command ChBox:"&Prompt" Purpose A Check Box. Options Row:10 Set row. Col:10 Set column. Wid:20 Set width of highlighted prompt. Check:"Expr" Box is checked if Expression is True. Action:"Expr" Expression is executed when box is selected. Before:"Expr" Expression is executed. If false box cannot be selected. Defaults Row One row below previous command. Col Same column as previous command. If previous command as Group, column is incremented to be inside of group box. Wid Prompt width. Highlight Prompt is highlighted when box is selected. Pressing Enter will check the box. Pressing the space bar will advance the cursor without checking the box. See Also Radio Notes Check boxes are boxes that contain an X if selected, and are empty if not selected. They are commonly used for selections that are cumulative. Radio buttons should be used when selections are mutually exclusive. The JORF Manual (Shareware Disk Version) 62 Button Command Button:"&Prompt" Purpose A Button. Options Row:10 Set Row Col:10 Set Column Wid:10 Set Width of Button Len:3 Set Length of Button Action:"Expr" Expression is executed when box is selected. Before:"Expr" Expression is executed. If false box cannot be selected. Defaults Row One row below previous command. Col Same column as previous command. If previous command as Group, column is incremented to be inside of the group box. Wid Prompt width plus two spaces on each side. Len 3. Highlight In the DOS version, the button is highlighted. Pressing Enter will select the button. Pressing the space bar will advance the cursor without selecting the button. Notes Buttons are used to complete screens or to select major options. They are not generally used for data entry purposes. The minimum length for a button in JORF is 3 lines. You cannot create "little" buttons. Example Ascii:Start Win:Add("ASCII TABLE", 4, 4, 19, 62, Here) Display:"Ascii:Show(0)" Marker:"Button" Button:"&Upper ASCII", Row:17 Col:1 Wid:30 Action:"Ascii:Show(128)" Chapter Four - The Window Manager 63 Marker:"Exit" Button:"E&xit ", Row:17 Col:33 Wid:30 Action:"Jorf:Exit()" Return Ascii:Show(Base) New (Char) Win:Attr("Lo") Move:To(1,1) | Display 128 Ascii characters For (Char = Base Thru 127+Base) Str:Put(To:Str(Char,"000 ")) Char:Put(Char) If ((Char %8)==7) Str:PutLine() Else Str:Put(" ") Win:Attr("No") | Change button to be the opposite of what is showing If (Base==0) Win:Chg("Button",17,1,19,33) Button:"&Upper ASCII", Row:17 Col:1 Wid:30 Action:"Ascii:Show(128)" Else Win:Chg("Button",17,1,19,33) Button:"&Lower ASCII", Row:17 Col:1 Wid:30 Action:"Ascii:Show(0)" Return (Ok) The JORF Manual (Shareware Disk Version) 64 Group Command Group:"&Prompt" Purpose A Group Box. Options Row:10 Set Row Col:10 Set Column Wid:40 Set Width of Box Len:6 Set Length of Box Defaults Row One row below previous command. Col Same column as previous command. Highlight Group boxes can never be selected, and are never highlighted. If a group box has an Alt key letter, and that key is pressed, the first field within the group box is highlighted. Notes A Group box is a single line box that surrounds one or more data entry fields. They are commonly used for surrounding related fields, and for surrounding multiple line text fields. A feature of the group boxes in JORF is to be able to use an Alt key to move to the first field of the box. Example This is the masin screen from the MAILLIST.J sample program. MailList:Start | Little Mail List Program New (Contact:Con) | Create Contact Structure Jorf:File ("MAILLIST.JCM",Here) | Set Database File Event:Add ("MailKey","Key",Here) | Set MailKey as a keystroke handler Mem:Ptr->IndexName = "FullName" | Index Name | The main screen with menu options Win:Add ("Josephine's Mail List Manager", 2, 2, 22, 78, Here) Menu:"&File" Menu:"&About " Action:"MailList:About" Menu: Menu:"&Rebuild ", Action:"Jorf:Rebuild" Menu: Menu:"E&xit Alt-X", Action:"MailKey:Esc_Key" Chapter Four - The Window Manager 65 Menu:"&Edit" Menu:"&Add Alt-A", Action:"MailList:Add(Con)" HotKey:"Alt_A_Key" Menu:"&Change Alt-C", Action:"MailList:Change(Con)" Menu:"&Delete Alt-D", Action:"MailList:Delete(Con)" HotKey:"Alt_D_Key" Menu:"&Search", Menu:"&Name ", Action:"MailList:KeySearch (Con, 'FullName' ) Menu:"&Company ", Action:"MailList:KeySearch (Con, 'Company' ) Menu:"&Last Name ", Action:"MailList:KeySearch (Con, 'LastName' ) Menu:"&Phone ", Action:"MailList:KeySearch (Con, 'WorkPhone') Menu:"&Zip ", Action:"MailList:KeySearch (Con, 'ZipCode' ) Menu:"&Reports" Menu:"&Mail List ", Action:"MailList:List()" Menu:"&This Contact ", Action:"MailList:PrintData(Con)" Menu:"&Lotsa Labels ", Action:"MailList:ContinLabels(Con,'All')" Menu:"&One Label", Action:"MailList:ContinLabels(Con,'One')" InpBefore:"MailList:Lock(Con)" Group:"&Browse List", Row:1 Col:41, Len:6, Wid:36 List:"" Field:"Con" Next:"MailList:NextRecord(Con,'Next')" Prev:"MailList:NextRecord(Con,'Prev')" Show:"MailList:Show(Con)" Before:"MailList:Write()" Display:"(Mem:Ptr->Locked==Null)" Group:"&Contact Name and Address", Row:1, Col:1, Wid:38, Len:6 Input:"Name ", Wid:30, Field:"Con->FullName" After:"MailList:SplitName(Con)" Input:"Company", Wid:30, Field:"Con->Company" Input:"Address", Wid:30, Field:"Con->Addr1" Input:" ", Wid:30, Field:"Con->Addr2" Input:" ", Wid:30, Field:"Con->Addr3" After:"MailList:ZipCode(Con)" Group:"Mail List Fields" Row:9 Col:1 Len:11 Wid:76 Input:"&Work Phone" Field:"Con->WorkPhone" Row:10 Col:2 Wid:20 Input:"&Home Phone" Field:"Con->Homephone" Row:11 Col:2 Wid:20 Input:"Fax &Phone " Field:"Con->FaxPhone" Row:12 Col:2 Wid:20 Input:"Birthda&y " Field:"Con->BirthDay" Row:13 Col:2 Wid:20 Input:"C&omment " Field:"Con->Comment" Row:15 Col:2 Wid:50 Input:"&Last Name " Field:"Con->LastName" Row:10 Col:35 Wid:14 Input:"Dear " Field:"Con->Dear" The JORF Manual (Shareware Disk Version) 66 Row:11 Col:35 Wid:14 Input:"Zip Code " Field:"Con->Zipcode" Row:12 Col:35 Wid:14 Radio:"Fr&iend" Check:"Con->Type=='Friend'" Action:"Con->Type='Friend'" UnAction:"Con->Type= Null" Row:10 Col:62 Radio:"Fa&mily" Check:"Con->Type=='Family'" Action:"Con->Type='Family'" UnAction:"Con->Type= Null" Row:11 Col:62 Radio:"Clien&t" Check:"Con->Type=='Client'" Action:"Con->Type='Client'" UnAction:"Con->Type= Null" Row:12 Col:62 Radio:"&Vendor" Check:"Con->Type=='Vendor'" Action:"Con->Type='Vendor'" UnAction:"Con->Type= Null" Row:13 Col:62 HLine:"&Notes" Row:16 Col:2 Len:1 Wid:76 Text:"" Field:"Con->Notes" Row:17 Col:2 Len:4 Wid:76 Return (Ok) | That is all, Folks! Chapter Four - The Window Manager 67 Input Command Input:"&Prompt" Purpose An Input Field. Options Row:10 Set Row Col:10 Set Column Wid:10 Set Width of Data Entry Len:3 Set Length of Data Entry After:"Expr" Expression is executed after input.. Before:"Expr" Expression is executed. If false input is skipped. Field:"Value" Field Value to be entered. Type:"DType" Set data type for automatic conversion. "DType" can be "Date" or "Number". Format:"##,###.00" If Type is "Number", numeric format for display. Will be unformatted for entry. Defaults Row One row below previous command. Col Same column as previous command. If previous command as Group, column is incremented to be inside the group box. Wid 30 Len 1 Highlight Input fields are highlighted with attribute 4 when not active, and attribute 5 when they are being edited. Also, the cursor is displayed when they are being edited. The prompt is never highlighted. See Also Text. Notes Input is used to enter single line prompts and small multi line prompts. Data entry fields are highlighted both during entry and when displayed on the screen. The JORF Manual (Shareware Disk Version) 68 Example This program, Payment.J contains both Type and Format commands. For extra fun, try this one with "Set Decimal=," (comma decimal) in your INI file. Class:Payment (Amt,Yrs,Intr,Pmt,Pmt50,Yrs50) Payment:Start New (Payment:Pmt) Win:Add ("Loan Payment Calculator",5,20) String:"Calculate your loan payment amount and years" String:"to pay if you added just $50 to the payment." String: String:"Press the TAB key to get from one field to" String:"the next. ENTER will end the program." Input:"&Loan Amount ", Row:7 Col:5 Wid:14 Field:"Pmt->Amt", After:"Payment:Calc(Pmt)" Format:"###,###,###.00", Type:"Numeric" Input:"&Years to Pay ", Row:8 Col:5 Wid:3 Field:"Pmt->Yrs", After:"Payment:Calc(Pmt)" Format:"###", Type:"Numeric" Input:"&Percent Interest ", Row:9 Col:5 Wid:8 Field:"Pmt->Intr", After:"Payment:Calc(Pmt)" Format:"#0.0000%", Type:"Numeric" Input:"Payment ", Row:10 Col:5 Wid:14 Field:"Pmt->Pmt", Before:"Return(Null)" Format:"###,###,###.00", Type:"Numeric" Input:"Adding just $50 ", Row:12 Col:5 Wid:14 Field:"Pmt->Pmt50", Before:"Return(Null)" Format:"###,###,###.00", Type:"Numeric" Input:"Reduces the years to" Row:13 Col:5 Wid:3 Field:"Pmt->Yrs50", Before:"Return(Null)" Format:"###", Type:"Numeric" Button:" &Done ", Row:15, Col:16 Return(Ok) Payment:Calc(Pmt) New (Periods,Per_Intr,Payment,Months50) Pmt->Pmt = 0 If (Pmt->Intr > 0 And Pmt->Yrs > 0) Periods = Pmt->Yrs*12 Per_Intr = Pmt->Intr/12/100 Payment = (Pmt->Amt*Per_Intr) / (1-Num:Pow(1+Per_Intr,(-Periods))) Payment = Num:Int((Payment+.005)*100)/100 Pmt->Pmt = Payment Pmt->Pmt50 = Payment+50 Chapter Four - The Window Manager 69 Months50 = Num:Log(Pmt->Pmt50/(Pmt->Pmt50-Pmt->Amt*Per_Intr)) Months50 = Months50/Num:Log(1+Per_Intr) Pmt->Yrs50 = Num:Int((Months50/12)*10)/10 Win:Dsp Return (Ok) The JORF Manual (Shareware Disk Version) 70 List Command List:"" Purpose A pick list of records. Options Row:10 Set Row Col:10 Set Column Wid:10 Set Width of List Len:3 Set Length of List After:"Expr" Expression is executed after list.. Before:"Expr" Expression is executed. If false cannot pick from list. Next:"Expr" Command to execute for Next Record Prev:"Expr" Command to execute for Prev Record Show:"Expr" Command to execute to display entry Defaults Row One row below previous command. If the previous command is a Group Box, then Row, Col, Wid and Len default to the inside dimensions of the box. Col Same column as previous command. Wid 30 Len 1 Highlight Lists are highlighted like menus. When the list position is changed using the mouse or arrow keys, the screen is automatically redisplayed. No cursor is displayed, even when the list has focus. See Also Array. Notes This has got to be my favorite window feature. This command is used to display information that is contained in different records, where an Array list can only display arrays. Since you control the next and Chapter Four - The Window Manager 71 prev functions, it is easy to make the list indexed, to filter it, and to format the displayed text. Lists are relatively slow, since it takes several record reads to display several records. For this reason, you should keep your lists as short as you can, since this limits the number of records required for a display operation. Example See the MailList.J sample program, especially what happens when you change your index to the Zip code index. The JORF Manual (Shareware Disk Version) 72 Marker Command Marker:"Markername" Purpose Mark a section of input fields and buttons for later replacement using Win:Chg. Options None See Also Win:Chg. Notes More sophisticated data entry windows contain buttons and fields that change according to what is entered on the screen. The way to make this happen in JORF land is to set markers around those fields, and then use Win:Chg to set new fields in their place. Markers do not display, cannot be highlighted, and cannot have After or Action clauses. Before and Display clauses probably work, however, and tagging them to a non-displaying element allows you to closely control when these operations are performed. Chapter Four - The Window Manager 73 Menu Command Menu:"&Prompt" Purpose A Menu Bar or Menu Line. Options Action:"Expr" Expression to execute when selected. Hotkey:"Keystroke" Hotkey accelerator Menu:"&Prompt" (Indented) SubMenu Options See Also MLine. Notes The Menu command is used for Menu bars and associated pull down menu boxes. Each menu command contains either an Action, or it has indented sub-menu commands below. A menu option cannot have both. The top level menu is assumed to be a menu bar on the top of the current window. To force top level menu to be menu lines, use MLine. All indented sub-menu commands are menu lines, even when declared using the Menu command. The JORF Manual (Shareware Disk Version) 74 MLine Command MLine:"&Prompt" Purpose A Menu Line. Options Action:"Expr" Expression to execute when selected. Hotkey:"Keystroke" Hotkey accelerator Menu:"&Prompt" (Indented) SubMenu Options See Also Menu. Notes The MLine command is used to force a menu to use menu lines, even when it is a top level menu. For Menu bars, use Menu. I don't think the use of MLine is CUA compliant, since no CUA screen uses a menu-lines as a top level menu (i.e. the whole window contains one menu. Chapter Four - The Window Manager 75 Prompt Command Prompt:"&Prompt" Purpose A Highlightable Prompt. Options Row:10 Set Row Col:10 Set Column Wid:30 Set Width of highlight area. Action:"Expr" Executes Expression when selected. Before:"Expr" Executes Expression, If false prompt cannot be selected. Defaults Row One row below previous command. If used in brackets in text, defaults to current text position. Col Same column as previous command. If previous command as Group, column is incremented to be inside of the group box. If used in brackets in text, defaults to current text position. Highlight Prompts are highlighted when they are active. Pressing Enter when highlighted will select the prompt. Pressing the space bar will move the cursor downward. See Also String. Notes Prompts are used primarily for Hypertext. In this case, they are commonly defined within the text in curly brackets. For prompts that are never highlighted, like screen subtitles or text, see String. Prompts may also be aligned in a row, producing a menu bar menu in the middle of a text screen. You can see an example of this usage in the opening screen of The JORF Tutorial, where the hypertext options are a "Prompt Menu" The JORF Manual (Shareware Disk Version) 76 Example An enterprising user gave me this program (with a bug to fix) and I really like it. Try DOS.J. Dos:Start Win:Add("Jo's DOS Function Utility", 0, 0, 20, 44) This program allows the user to & select special DOS commands. Place your mouse over the desired & selection and click the Left Mouse & Button or you may use the up and down & arrow keys to select the desired command. {Group:"DOS Commands" Row:9 Col:5 Len:10 Wid:30} {Prompt:"&Memory Stats " Row:11 Col:7 Wid:25 Action:"Dos:Cmd('Mem')"} {Prompt:"&Command Shell " Row:12 Col:7 Wid:25 Action:"Dos:Cmd('Shell')"} {Prompt:"Directory by &Date" Row:13 Col:7 Wid:25 Action:"Dos:Cmd('DirDate')"} {Prompt:"Directory by &Size" Row:14 Col:7 Wid:25 Action:"Dos:Cmd('DirSize')"} {Prompt:"&Type in a Command" Row:15 Col:7 Wid:25 Action:"Dos:Cmd('TypeIt')"} {Prompt:"&Windows Program " Row:16 Col:7 Wid:25 Action:"Dos:Cmd('Windows')"} {Prompt:"E&xit " Row:18 Col:7 Wid:25 Action:"Return(Null)"} Return (Ok) Dos:Cmd(Action) New (Command, Flags, Message) Switch (Action) Case 'Mem' Command = "Mem /c | More" Flags = "CP" Case 'Shell' Command = Null Flags = "C" Message = "Type 'EXIT' to return to JORF" Case 'DirDate' Command = "Dir /o-d | More" Flags = "CP" Message = "Sorting . . ." Case 'DirSize' Command = "Dir /o-s | More" Flags = "CP" Message = "Sorting . . ." Case 'TypeIt' Win:Add Input:"Command to execute:", Field:"Command" If (Kbd:Got=='Esc_Key') Return Flags = "C" Case 'Windows' If (Jorf:Info("Windows")==False) Msg:Add This option only works in the & Chapter Four - The Window Manager 77 Windows version of the JORF interpreter. Return Win:Add Input:"Windows program:", Field:"Command" If (Kbd:Got=='Esc_Key') Return Flags = "W" Else Msg:Add Illegal DOS Command "{Action}". Return (Ok) Jorf:System (Command, Flags, Message) Return (Ok) The JORF Manual (Shareware Disk Version) 78 Radio Command Radio:"&Prompt" Purpose A Radio Button. Options Row:10 Set row. Col:10 Set column. Wid:20 Set width of highlighted prompt. Check:"Expr" Box is checked if Expression is True. Action:"Expr" Expression is executed when box is selected. Before:"Expr" Expression is executed. If false box cannot be selected. Defaults Row One row below previous command. Col Same column as previous command. If previous command as Group, column is incremented to be inside the group box. Wid Prompt width Highlight Prompt is highlighted when box is selected. Pressing Enter will check the box. Pressing the space bar will advance the cursor without checking the box. See Also ChBox Notes Radio buttons are circular boxes that contain a dot if selected and are empty if not selected. They are commonly used for selections that are exclusive. Use Check boxes for selections that are cumulative. Chapter Four - The Window Manager 79 String Command String:"&Prompt" Purpose An unhighlighted prompt. Options Row:10 Set Row Col:10 Set Column Defaults Row One row below previous command. If used in brackets in text, defaults to current text position. Col Same column as previous command. If previous command as Group, column is incremented to be inside of the group box. If used in brackets in text, defaults to current text position. Highlight Strings are never highlighted. If they contain an Alt key selection, and that key is pressed, the next following entry item is highlighted. See Also Prompt. Notes Strings are used to place plain text at certain row and column positions on data entry screens. Strings are never highlighted. The JORF Manual (Shareware Disk Version) 80 Text Command Text:"" Purpose A text input area. Options Row:10 Set Row Col:10 Set Column Wid:60 Set Width of Data Entry Len:6 Set Length of Data Entry After:"Expr" Expression is executed after input.. Before:"Expr" Expression is executed. If false input is skipped. Field:"Value" Field Value to be entered. Defaults Row One row below previous command. Col Same column as previous command. If previous command as Group, column is incremented to be inside of the group box. Wid If previous command was a group box, width is set to the inside width of the group box. Len If previous command was a group box, length is set to the inside length of the group box. Highlight Text fields are not highlighted like input fields. They remain the normal background color, even during data entry. The cursor is displayed when a text box is being edited. It is not common to prompt Text input fields. See Also Input. Notes Text fields are similar to input fields, except for the highlighting. Word processing is usually easier using the normal screen color, instead of the field highlight color. Text input uses the screen color. Chapter Four - The Window Manager 81 Example This is the TextEdit.J sample program, that gives you a basic text editor in less than 200 lines of source code. TextEdit:Start(Name) Mem:Ptr->Name = To:Ucs(Name) Mem:Ptr->Edit = TextEdit:Read(Mem:Ptr->Name) Event:Add(Null) | Block prior events Event:Add("EditKey") | Use standard Edit Keys Event:Add("TextEdit") | and some special ones defined here Jorf:File("TextEdit.Tmp",Here) | Temporary Storage area If (Name == Null) Kbd:Put("F4_Key") Win:Add("Josephine's Text Editor", 0, 0, 0, 0, Here) Save:"TextEdit:Save" Restore:"Null" Idle:"EditKey:Message" | When idle - display Row Col info Flrco:"o" | No wrap mode Menu:"&File" Menu:"&New Shift-F4", Action:'TextEdit:New' HotKey:"Shift_F4_Key" Menu:"&Open F4", Action:'TextEdit:Open' HotKey:"F4_Key" Menu:"&Save Shift-F3", Action:'TextEdit:Save' HotKey:"Shift_F3_Key" Menu:"Save &As F3", Action:'TextEdit:SaveAs' HotKey:"F3_Key" Menu:"" Menu:"&Print F5", Action:'TextEdit:Print' HotKey:"F5_Key" Menu:"" Menu:"A&bout" Action:'TextEdit:About' Menu:"E&xit Alt-X", Action:'TextEdit:Exit' HotKey:"Alt_X_Key" Menu:"&Edit" Menu:"&Toggle Insert Mode Ins", Action:'TextEdit:Stuff("Ins_Key")' Menu:"&Beginning of line Home", Action:'TextEdit:Stuff("Home_Key")' Menu:"&End of line End", Action:'TextEdit:Stuff("End_Key")' Menu:"Word &Left Ctrl-A", Action:'TextEdit:Stuff("Ctrl_A_Key")' Menu:"Word &Right Ctrl-F", Action:'TextEdit:Stuff("Ctrl_F_Key")' Menu:"&Delete Word Ctrl-T", Action:'TextEdit:Stuff("Ctrl_T_Key")' Menu:"De&lete to End Ctrl-K Y", Action:'TextEdit:Stuff("Ctrl_K_Key", "Y_Key")' Menu:"&Block" Menu:"&Beginning Ctrl-K B", Action:'TextEdit:Stuff("Ctrl_K_Key","B_Key")' Menu:"&End Ctrl-K K", Action:'TextEdit:Stuff("Ctrl_K_Key","K_Key")' Menu:"&Delete Ctrl-K Y", Action:'TextEdit:Stuff("Ctrl_K_Key","Y_Key")' Menu:"&Copy Ctrl-K C", Action:'TextEdit:Stuff("Ctrl_K_Key","C_Key")' Menu:"&Move Ctrl-K V", Action:'TextEdit:Stuff("Ctrl_K_Key","V_Key")' Menu:"&Hide Ctrl-K H", Action:'TextEdit:Stuff("Ctrl_K_Key","H_Key")' Menu:"&Goto" Menu:"&Beginning of file Ctrl-Q R", Action:'TextEdit:Stuff("Ctrl_Q_Key","R_Key")' The JORF Manual (Shareware Disk Version) 82 Menu:"&End of file Ctrl-Q C", Action:'TextEdit:Stuff("Ctrl_Q_Key","C_Key")' Menu:"&Line Number Ctrl-Q G", Action:'TextEdit:Stuff("Ctrl_Q_Key","G_Key")' Menu:"&Search" Menu:"&Find Ctrl-Q F", Action:'TextEdit:Stuff("Ctrl_Q_Key","F_Key")' Menu:"Find &Next Ctrl-L", Action:'TextEdit:Stuff("Ctrl_L_Key")' Menu:"&Replace Ctrl-Q A", Action:'TextEdit:Stuff("Ctrl_Q_Key","A_Key")' Text:'', Field:'Mem:Ptr->Edit' Row:1 Col:1 Wid:78 Len:22 File:Del("TextEdit.Tmp") | Delete Storage area Return TextEdit:About Msg:Add ("About TextEdit", "Ok") Version 1.1 May 11, 1992 Copyright (C) 1991,1992 by The JORF Company Return (Ok) TextEdit:New() If (TextEdit:Save) EditKey:Ctrl_Page_Up_Key Mem:Ptr->Name = Null Mem:Ptr->Edit = Text:Add() Win:Dsp Return (Ok) TextEdit:Open New (Name) Name = DirList:GetFile("*.txt") If (Name) If (TextEdit:Save) Mem:Ptr->Name = To:Ucs(Name) Mem:Ptr->Edit = TextEdit:Read (Name) Win:Dsp Return (Ok) TextEdit:Print() New (Dest) Dest=Jorf:Printer() File:Save("JREPORT.LST",Mem:Ptr->Edit) File:Print("JREPORT.LST",Dest) Return(Ok) TextEdit:Read(FileName) If (FileName) If (File:Exist (FileName)) Win:Add ('Reading') Loading file "{FileName}" Return (File:Load (FileName)) Else Msg:Add ('Error', 'Ok') Chapter Four - The Window Manager 83 Cannot find file "{FileName}" Return (Text:Add) TextEdit:Save If (Mem:Ptr->Name==Null) TextEdit:SaveAs() Else TextEdit:Write (Mem:Ptr->Name, Mem:Ptr->Edit) Jorf:Del (Win:Ptr->Copy) Win:Ptr->Copied=False Return (Ok) TextEdit:SaveAs New (Key, FileName) FileName = Mem:Ptr->Name While (Ok) Win:Add ('File Name') Input:'File Name to Save ', Wid:30, Field:'FileName' Win:Del If (Kbd:Got == 'Esc_Key') Return (Ok) If (FileName != Null) If (File:Exist (FileName) != 0) Key=Msg:Add ('File Already Exists' 'No') File "{FileName}" Already Exists! Do you want to overwrite it? If (Key==Null) | If not ok - loop back to while OK Continue Break | Otherwise break and write file Mem:Ptr->Name = To:Ucs(FileName) TextEdit:Write (Mem:Ptr->Name, Mem:Ptr->Edit) Jorf:Del (Win:Ptr->Copy) Win:Ptr->Copied=False Return (Ok) TextEdit:Stuff (Key1,Key2) Kbd:Put(Key1) Kbd:Put(Key2) Return(Null) TextEdit:Write (FileName, Text) If (FileName And Text) Win:Add ('Writing') Saving file "{FileName}" File:Save (FileName, Text) Return (Ok) The JORF Manual (Shareware Disk Version) 84 Chapter Five JORF Functions JORF Functions In JORF, as in all object oriented languages, a Method for one object often invokes a method for another object. This process continues until finally, a low level object invokes a library routine. For example the command Print (integer:A) invokes the Integer:Print(A) Method that may then invoke the Number:Print(A) Method that invokes the Jorf:Print(A) Method. At some point, control is passed to the underlying system that prints the data. The JORF Function library is implemented in the C language. This library is not object oriented nor is it interpreted so there is no ability for polymorphism or inheritance on this level. JORF Library calls are made without any regard to class or inheritance. All parameters passed into C language calls are treated as generic JORF pointers, and return values take on the class of the first parameter that was passed in. Chapter Four - The Window Manager 85 Arr:Del Function Arr:Del ( Array, Position, Count ) Purpose Delete Count elements from Array, starting with the indicated Position. Returns Array. See Also Arr:Ins Notes Array handling is usually done by referencing individual array items. Arrays do not need to be declared, and are created simply by setting values to their elements. Arr functions are used to change the whole array, without reference to the elements. The Arr:Del command may be used to delete one or more elements in the middle of an array. It automatically decrements succeeding elements so the array shrinks in size by the number of elements deleted. The JORF Manual (Shareware Disk Version) 86 Arr:Dir Function Arr:Dir ( WildCard, Ext_Exclusion_List ) Purpose Return an Array of files on the current directory that match the designated WildCard but are not in the Extension Exclusion List. Returns Array. See Also Arr:Sort, Arr:Pick, File:ChgDir. Notes The easiest way to get and display a list of files on the current directory. Arr:Dir with no parameters will get a list of all files on the current directory. Files may be read according to the designated wildcard. This may be any valid DOS wildcard symbol, just as you would use from DOS. The following command makes a list of all the text files on a directory: Arr:Dir("*.TXT") Files with certain extensions can be excluded by including them in the extension exclusion list. This list is a string with a list of extensions separated by commas. Two commas together indicate files without extensions. The following command will collect a list of all files except those with .BAK, .OBJ, .INI or no extension. Arr:Dir("*.*", "BAK,OBJ,INI,,") The Arr:Del command may be used to delete one or more elements in the middle of an array. It automatically decrements succeeding elements so the array shrinks in size by the number of elements deleted. If the WildCard has the value "Subdir", then the file list will be a list of subdirectories. Otherwise, it will only contain files. Example The DIRLIST.J program is also compiled into the runtime system and documented as DirList:GetFile. Class:DirList | Class Definition Name | File Name Path | File Path WildCard | Wildcard for directory Chapter Five - JORF Functions 87 ExclusionList | Extension Exclusion List FileArray | Array of files on this path DirArray | Array of other paths DirList:Start | FOR TESTING: Start routine New (FileName) FileName = DirList:GetFile("*.*",Null) Msg:Add File name is {FileName} Return (Ok) DirList:Cancel(List) | Routine to Cancel data entry List->Name=Null | Signal that we canceled Return(Null) | Returning Null will finish input DirList:Done(List,Name) | Routine to finish data entry If (Str:In(List->Name,"*") Or Str:In(List->Name,"?")) List->WildCard = List->Name List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) Kbd:Put("Home_Key") | Stuff home key Win:Dsp | Redisplay (including arrays) Return (Ok) If (List->Name==Null) | If name is still null display message Msg:Add Please select a file name or "Cancel". Return (Ok) | Returning Ok will continue input Return (Null) | Returning Null will finish input DirList:FileArray(WildCard,Exclusionlist) | Read a file array New (Array,OldMessage) If (WildCard!='SUBDIR') If (Win:Ptr) OldMessage = Win:Msg('Reading Directory') Else Win:Add("Reading") Reading Directory Array = Arr:Dir (WildCard, ExclusionList, 12) If (WildCard!='SUBDIR') Win:Msg(OldMessage) Return (Array) DirList:GetFile(WildCard,ExclusionList) New (OrigPath, DirList:List, DirChoice, FileChoice) | Initalize values OrigPath = File:ChDir() List->Path = OrigPath List->WildCard = WildCard List->ExclusionList = Exclusionlist List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) List->DirArray = DirList:FileArray("SUBDIR") The JORF Manual (Shareware Disk Version) 88 Event:Add(Null) | Block prior keystroke events Win:Add ("Get File Name", 0, 0, 10, 56, Here) Type:"Message" | Input File Name Input:"File&name: ", Wid:24, Row:2, Col:3, Field:"List->Name" | Files array with a group box around Group:"&Files", Row:6, Col:2, Wid:16, Len:10 Array:"", Field:"List->FileArray", Choice:"FileChoice", Action:"DirList:NewName(List,List->FileArray[FileChoice])" | Directories array with a group box around Group:"&Directories", Row:6, Col:22, Wid:16, Len:10 Array:"", Field:"List->DirArray", Choice:"DirChoice" Action:"DirList:NewDir(List,List->DirArray[DirChoice])" | Input File Path Input:"Directory: ", Wid:24, Row:4, Col:3, Field:"List->Path" After:"DirList:NewDir(List,List->Path)" | Two buttons Button:" &Ok ", Row:1, Col:42, Wid:14 Action:"DirList:Done(List,List->FileArray[FileChoice])" Button:" &Cancel ", Row:4, Col:42, Wid:14 Action:"DirList:Cancel(List)" If (File:ChDir(OrigPath)) If (List->Name) If (Str:At(List->Path,Str:Len(List->Path),1)=='\') Return (List->Path+List->Name) Return (List->Path+'\'+List->Name) Return (Null) DirList:NewDir(List,Path) | Routine to set a new path If (File:Chdir(Path)) | Change to the new path List->Path = File:ChDir() | Reset path name List->Name = Null | Set file name to null | Re-read file array List->FileArray = DirList:FileArray(List->Wildcard, List->Exclusionlist) | Re-Read directory array - special argument "SUBDIR" does this List->DirArray = DirList:FileArray("SUBDIR") Win:Dsp | Redisplay Window Return(Ok) | Returning Ok continues input DirList:NewName(List,Name) | Routine to set a new name List->Name = Word:At(Name,1) | Set the name (Easy!) Win:Dsp | Redisplay the screen Kbd:Put("Home_Key") | And go back to file name Return(Ok) | Returning OK will continue input Chapter Five - JORF Functions 89 Arr:Ins Function Arr:Ins ( Array, Position, Count ) Purpose Insert Count elements into Array, starting with the indicated Position. Returns Array. See Also Arr:Del Notes Array handling is usually done by referencing individual array items. Arrays do not need to be declared, and are created simply by setting values to their elements. Arr functions are used to change the whole array, without reference to the elements. The Arr:Ins command may be used to insert one or more elements in the middle of an array. It automatically increments succeeding elements so the array grows in size by the number of elements inserted. The JORF Manual (Shareware Disk Version) 90 Arr:Len Function Arr:Len ( Array ) Purpose Returns the highest offset in the array. Returns Integer Offset. See Also Word:Len Notes Returns the length of an array. Actually, returns the offset of the highest element of the array, which is also the length if the first element is element number 1. Arrays may contain element 0, and also negative elements. If this is the case, the actual length may be longer than the value of this command. Example This program is pretty old, written before there were buttons and a nice window manager. For that reason, it shows pretty well the Arr:Len and Arr:Pick commands that are hidden when you use DirList:GetFile. Dump:Start New (WildCard, FileList, Choice) New (FileName, Char, Length, Pos, Col) While (Ok) | First get a wildcard for dir command Win:Add ("Dump a File") Input:"Directory WildCard: ", Field:"WildCard" If (Kbd:Got = 'Esc_Key') Return | Read the directory Win:Add("Reading Directory") One Moment Please . . . FileList = Arr:Dir(WildCard) If Arr:Len(FileList) < 1 Msg:Add No Files match the WildCard! Else While FileList != Null | And ask to pick a file Choice = Arr:Pick(FileList,Null,"Dump File", 0, 0, 0, Choice) If Kbd:Got = 'Esc_Key' Break Chapter Five - JORF Functions 91 | Got a file name! FileName = FileList[Choice] FileName = Str:At (FileName 1, Str:In(FileName," ")) Length = File:Len (FileName) Pos = 0 Win:Add (FileName, 2, 8, (Length/16)+2, 78, Here) While (Pos < Length) Col = (Pos % 16) | Set column position If (Col == 0) | If beginning new line If (Pos > 0) | If after first line Move:By (1,0) | Start a new line Move:To (0,1) | Str:Put (To:Str(Pos,"0000:0000",16)) ++Pos | Read One Character Char = File:Read (FileName,1,Pos) | And Display It . . . Move:To (0,13+(Col*3)) Str:Put (To:Str(To:Ascii(Char),'00',16)) Move:To (0,62+Col) Char:Put (To:Ascii(Char)) If Kbd:Hit | If key hit Char = Kbd:Get | See What it is If Char = "Esc_Key"| If Escape Break | Break Win:Pause | Pause Str:PutLine | One more line Str:PutLine | One more line Win:Msg("End of File") | Done! Win:Pause | Wait Win:Del | Delete window Win:Del Win:Del Win:Del Return | Exit The JORF Manual (Shareware Disk Version) 92 Arr:Pick Function Arr:Pick (Array, Command, Title, Row, Column, Length, Default) Purpose Display a browser menu of array items with Title, at Row and Column, no longer than Length and highlighting Default. Returns Integer offset of selection or "Esc_Key". See Also Arr:Sort Notes One of the more powerful JORF command, this is what displays the file list when you start the JORF interpreter, and also what displays the debugger Alt-B browser lists. This command returns Null, if Array is blank or not an array. All other parameters may be omitted. The Length is only the maximum to display. If the array is shorter, then the menu length will be the length of the array. If the array is longer, then it will scroll automatically. The Array pick does not set or block keystroke events, and existing events often interfere with array selection. To prevent this, it is typical to include do Event:Add with no parameters before calling Arr:Pick. Adding a null keystroke event blocks processing from searching down the stack to process lower level keystroke events. Menu options are displayed as strings. Both Arr:Pick and Arr:Sort make use of a polymorphic Command to get the value of these strings. If command is Null, the normal string value is used. For structures, you can set up a method that returns a string that represents that structure. for instance, the Address structure may show Name, City and State: Class:Address, Name, Addr1, Addr2, City, State, Zip Address:Show(Addr) Return (Str:Pad (Addr->Name, 30)+" "+Addr->City+", "+Addr->Zip) Example See Arr:Len and the Dump.J sample program. Chapter Five - JORF Functions 93 Arr:Printers Function Arr:Printers Purpose Return an Array of available printers. Returns Array. See Also Arr:Pick, Jorf:Printer and JORF.INI documentation in Appendix D. Notes This command reads the printers listed in your JORF.INI or JORFWIN.INI file and creates an array. You can use this array on a data entry screen or with the Arr:Pick function. Each entry can be assumed to be a string that contains a description, and a printer designation. The printer is assumed to be the last word of the command. Example This is not a sample program, but the actual code that is converted to C and run when you use the Jorf:Printer function. If you wish, you can type it in quickly to play with it to make your own printer selection menu. Jorf:Printer New (PrintList,PrintChoice,Dest) Event:Add() PrintList = Arr:Printers() Win:Add("Select Printer") Group:"&Printers", Row:1 Col:1 Len:6 Wid:22 Array:"" Field:"PrintList" Choice:"PrintChoice" Button:" &Go " Row:1 Col:32 Action:"Dest=PrintList[PrintChoice]" Button:" &Cancel " Row:4 Col:32 Action:"Return ('Esc_Key')" If (Dest='Esc_Key' Or Kbd:Got='Esc_Key') Dest=Null Return(Dest) The JORF Manual (Shareware Disk Version) 94 Arr:Sort Function Arr:Sort ( Array, Command, Direction ) Purpose Sort the elements of an array. Returns Array. Notes The only sort command in the JORF language. Normally sorts elements in ascending order. You can sort descending by specifying a Direction of "Down" or "Descending" (or anything that begins with the letter 'D'). Arr:Sort makes use of a polymorphic Command to get the string value of the array element. If this is Null then the string value is used. If not null, the Command should be a method that takes exactly one parameter. The parameter will be filled with the value being sorted. The method must return a string value that represents the sort index value. Class:Address, Name, Addr1, Addr2, City, State, Zip Address:SortString(Addr) Return (Addr->Name) Chapter Five - JORF Functions 95 Example For normal use, see Arr:Len and the Dump.J sample program. For use of Arr:Sort with a Command, the Help.J program uses this combination to sort an array of structure pointers. Here are a coupe methods from that program. Class:Help (Index:Help, Array, A1, A2, A3) Class:HelpArr (Name Array) Help:CatName(Harr) Return (Harr->Name) Help:Load() New (Rule:Rule, Help:HelpPtr, Name, Pos) HelpPtr->Help = "Help" Jorf:Write (HelpPtr) Rule->Obj="Help" Rule->Prob=100 Rule->Type=121 Rule->KLen=1 Win:Add ("Loading Help Information") While (Ok) Rule:Next (Rule) If (Rule->Fnd) Name = Word:At(Rule->Ptr,1) Str:Put (Name) Str:Put (" - ") Switch Case Str:In (Name, ":") Help:PutEntry(HelpPtr,Null,Name) Case Str:Len (Name) <= 2 Or Str:In(Name,"or") Help:PutEntry(HelpPtr,"[Math]",Name) Case Str:Len (Name), < 4 Case Str:In (Name, "/") Case Str:In ("True False Return Else Null Here", (Name) ) Help:PutEntry(HelpPtr,"[Control]",Name) Case (Str:Len (Name) > 0) Help:PutEntry(HelpPtr,"[Win]",Name) Else Break Arr:Sort(HelpPtr->Array,"Help:CatName") Jorf:Write(HelpPtr) Return (HelpPtr) The JORF Manual (Shareware Disk Version) 96 Char:Del Function Char:Del ( Count ) Purpose Delete Count characters in the current window at the current cursor position. Returns None. See Also Char:Ins Notes This command does two specific things; 1) it deletes Count characters at the current location in the current window, and 2) it deletes Count characters in the line currently being edited. The line edit buffer is separate from the screen, although they usually reflect the same data. The line and paragraph may rewrap if the window Magic is True and the window FLRCO is not "Off". Example The Charex.J sample program shows one way to use the Char:Ins and Char:Del functions. Because these functions operate only on the screen, they are most appropriate to methods that change text that is being edited on the screen. CharEx:Start New Count, Str1, Str2 Str1="This Text will Disappear" Str2="This Text will Appear" Win:Add ("Char Example", 10, 25, 30, 2, Here) Str:Put (Str1) | Show Str1 Win:Pause (20) | And pause for Effect Count = Str:Len (Str1) | Set Counter While (Count > 0) | While GT Zero Move:To (1,1) | First line Char:Del (1) | Take 1 Away Move:To (2,1) | Second line Char:Ins (1) | Add one, Add char Char:Put (To:Ascii (Str:At (Str2, Count, 1))) --Count | Decrement Count Win:Pause(5) | Pause 5/100 seconds Win:Pause | Done! Return | Bye Chapter Five - JORF Functions 97 Char:Get Function Char:Get Purpose Gets a character displayed on the current window. Returns ASCII decimal value of the character. See Also Char:Put. Notes To get a keystroke value, use Kbd:Get. This function reads the value off the screen, assuming that you put something there worth reading. The value returned is numeric, because the most common use of this function is to handle OEM characters. This command is symmetrical to Char:Put. The JORF Manual (Shareware Disk Version) 98 Char:Ins Function Char:Ins ( Count ) Purpose Insert Count spaces in the current window at the current cursor position. Returns None. See Also Char:Del Notes This command does two specific things; 1) it inserts Count spaces at the current location in the current window, and 2) it inserts Count spaces in the line currently being edited. The line edit buffer is separate from the screen, although they usually reflect the same data. If the line length exceeds the window boundary, and window is in one of the wrap modes, the line and paragraph will be reformatted. This formatting takes place only on the screen, and not in the edit buffer. Example See Char:Del. Chapter Five - JORF Functions 99 Char:Put Function Char:Put ( Value ) Purpose Put an ASCII character on the current window at the current cursor location. Returns None. See Also Char:Get, Str:Put. Notes It is atypical for a JORF Language function to use ASCII values for characters. Usually, characters are strings and are displayed using Str:Put. However, some graphics characters are easier to display as numbers because they have no letter equivalent. This function is buffered for speed. Calling this function sets the internal buffer, but the buffer is not shown on the screen until the line is finished. You can force a display by changing to another line using Move:To or by ending the line using Str:PutLine. Example Ascii:Start New Char Win:Add("ASCII TABLE", 4, 4, 19, 74, Here) For (Char = 0 Thru 15) Move:To(1,(Char*4)+10) Str:Put(To:Str(Char)) Move:To(Char+3,1) Str:Put(To:Str(Char*16)) Move:To(2,1) Win:Attr("Lo") For (Char = 0 Thru 255) If ((Char % 16) == 0) Move:By(1,0) Move:To(0,10) Char:Put(Char) Move:By(0,3) Win:Msg("Press Enter to Continue") Win:Pause The JORF Manual (Shareware Disk Version) 100 Class:At Function Class:At ( Structure Position ) Purpose Returns class of word in parsed command line, or label of a structure member. Returns Class. See Also Class:AtPut, Word:At. Notes Structures, Arrays, the JORF stack, and lines of text are all stored as arrays of Class:Word pairs. The number of words in the array can be obtained using Word:Len. Structures Normally, you access structure elements using the pointer operator (->). However, you can also use this command to referencing the elements directly. Stack Each level of the stack (each method call) creates a new structure. The first element has the class Method and is the current program line. The second element has the class From and is the previous level of the stack. The next elements are the parameters in the order they were passed. Then, any New variables with the variable name standing for the class name. New Values New values that are structures contain a pointer to the class definition in the first element. Subsequent elements are various values in the order that they were referenced. Arrays Array elements are normally accessed using square brackets []. But if you find reason, you can use Word:At to get the element. Unlike Structures, array elements have no label, so the class will always be null. Using Class:At is legal, but will always return null unless you used Class:AtPut to put a value there. Chapter Five - JORF Functions 101 Text Text lines may be examined to obtain the class and values of items on that line. The line is automatically parsed when Class:At is used. The parse will automatically separate all words and punctuation characters. Each punctuation character is treated as a separate word. If the parsed line contains JORF-like Class:Word pairs, then the class values will be set for Class:At. The JORF Manual (Shareware Disk Version) 102 Class:AtPut Function Class:AtPut ( Structure, Position, Class ) Purpose Changes the class of a word in a member of a structure. Returns None. See Also Class:At, Word:AtPut. Notes Structures, Arrays, the JORF Stack and text lines are all stored as an array of Class:Word pairs. The number of words can be obtained using Word:Len. Although Class:At works for both text and structures, Class:AtPut works only on structures, not text lines. To change a text line, you must use the String functions. Class:AtPut can be used to change an element name in a structure, or a variable name in the stack. Chapter Five - JORF Functions 103 Class:In Function Class:In ( Structure, Class ) Purpose Searches for the existence of Class in a structure, and returns the position if it is found. Returns zero if Class is not found. Returns Position of Class or zero if not found. See Also Class:At, Word:In. Notes Both structures and text lines are stored as an array of Class:Word pairs. The number of words can be obtained using Word:Len. ClassIn can be used to see if a member exists in a structure, without using the structure pointer operator. The JORF Manual (Shareware Disk Version) 104 Date:Add Function Date:Add ( Date, Days, Months, Years ) Purpose Add the specified Days, Months, or Years to Date. Returns A date. See Also Date:Sub, Time:Add. Notes This is a very specialized command that helps you calculate one month after, or 90 days after a date. This command does all the necessary calculations to account for month lengths and leap years. Adding one month to 03/31 will result in 05/01, and not 04/30 as some people anticipate. Example The CAL.J program displays a calendar and uses Date:Add to add months as you press page down. Chapter Five - JORF Functions 105 Class:Cal | Declare class Calc Date | Day | Current day Month | Current entry value Year | Current year Row | Current Row Col | Current Col DspDay | Last displayed day DspMonth | Last displayed month DspYear | Last displayed year DspRow | Last displayed row DspCol | Last displayed col Cal:start New(Cal:Cal) Cal->Date = Date:Get Event:Add("Cal") Win:Add ("Calendar",0,0,9,20) Cal:Show(Cal) While (Ok) If (Kbd:Get()=='Esc_Key') Break Return (Cal->Date) Cal:Ctrl_Page_Down_Key Cal->Date = Date:Add(Cal->Date,0,0,1) Cal:Show( Cal ) Return (Ok) Cal:Ctrl_Page_Up_Key Cal->Date = Date:Sub(Cal->Date,0,0,1) Cal:Show( Cal ) Return (Ok) Cal:Down_Arrow_Key Cal->Date = Date:Add(Cal->Date,7,0,0) Cal:Show( Cal ) Return (Ok) Cal:End_Key Cal->Date = Date:Add(Cal->Date,6-(Date:Str(Cal->Date,'n')%7),0,0) Cal:Show( Cal ) Return (Ok) Cal:Enter_Key Msg:Add Date is {Cal->Date} Return ("Esc_Key") The JORF Manual (Shareware Disk Version) 106 Cal:Home_Key Cal->Date = Date:Sub(Cal->Date,(Date:Str(Cal->Date,'n')%7),0,0) Cal:Show( Cal ) Return (Ok) Cal:Left_Arrow_Key Cal->Date = Date:Sub(Cal->Date,1,0,0) Cal:Show( Cal ) Return (Ok) Cal:Page_Down_Key Cal->Date = Date:Add(Cal->Date,0,1,0) Cal:Show( Cal ) Return (Ok) Cal:Page_Up_Key Cal->Date = Date:Sub(Cal->Date,0,1,0) Cal:Show( Cal ) Return (Ok) Cal:Right_Arrow_Key Cal->Date = Date:Add(Cal->Date,1,0,0) Cal:Show( Cal ) Return (Ok) Cal:Show(Cal) New (Month, Day, Dow, Pos, Cnt, End) If (Date:Str(Cal->Date,'y') != Cal->DspYear) Cal->DspMonth=0 If (Date:Str(Cal->Date,'m') != Cal->DspMonth) If (Cal->DspDay) Move:To(Cal->DspRow,Cal->DspCol) Str:Put(To:Str(Cal->DspDay,"##")) Cal->DspDay=0 Month=Date:Str(Cal->Date,"S")+' '+Date:Str(Cal->Date,"YYYY") Move:To(1,1) Str:Put(Str:AtSet(Null,1,' ',Win:Ptr->Wid)) Move:To(1,(Win:Ptr->Wid-Str:Len(Month)+1)/2) Str:Put(Month) Move:To(2,1) Str:Put("____________________") Move:To(3,1) Str:Put("Su Mo Tu We Th Fr Sa") Dow =Date:Str(Cal->Date,'n') % 7 Day =Date:Str(Cal->Date,'d') End =Date:Add(Cal->Date,0,1) End =Date:Sub(End,Day) End =Date:Str(End,'d') Pos =Date:Str(Date:Sub(Cal->Date,Day-1),'n') % 7 Move:To (4,1) Chapter Five - JORF Functions 107 Str:Put(Str:AtSet(Null,1,' ',Win:Ptr->Wid)) For (Cnt = 1 thru End) Move:To(0,(Pos*3)+1) Str:Put(To:Str(Cnt,"##")) ++Pos If (Pos > 6) Move:By(1,0) Move:To(0,1) Str:Put(Str:AtSet(Null,1,' ',Win:Ptr->Wid)) Move:To(0,1) Pos=0 If (Pos == 0 Or Win:Ptr->CurRow < 9) Move:To (9,1) Str:Put(Str:AtSet(Null,1,' ',Win:Ptr->Wid)) Cal->DspYear = Date:Str( Cal->Date, 'y' ) Cal->DspMonth = Date:Str( Cal->Date, 'm' ) Cal->DspDay = 0 If (Date:Str(Cal->Date,'d') != Cal->DspDay) If (Cal->DspDay) Move:To(Cal->DspRow,Cal->DspCol) Str:Put(To:Str(Cal->DspDay,"##")) Cal->DspDay=0 Day =Date:Str( Cal->Date, 'd' ) Dow =Date:Str( Cal->Date, 'n' ) % 7 Cal->DspDay = Day Cal->DspRow = 4 + To:Int( ( Day - Dow + 5) / 7 ) Cal->DspCol = ( Dow * 3 ) + 1 Win:Attr( 5 ) Move:To( Cal->DspRow, Cal->DspCol ) Str:Put( To:Str( Cal->DspDay, "##" ) ) Win:Attr( 1 ) Return(Ok) Cal:Up_Arrow_Key Cal->Date = Date:Sub(Cal->Date,7,0,0) Cal:Show( Cal ) Return (Ok) The JORF Manual (Shareware Disk Version) 108 Date:Get Function Date:Get Purpose Get system Date. Returns A JORF pointer with the current system date. See Also Date:Set. Notes There is an internal data type for the date. Conversion to this type is done using the To:Date function. Conversion from this types done using Date:Str. These functions are paralleled for time. Chapter Five - JORF Functions 109 Date:Set Function Date:Set ( Date ) Purpose Set DOS clock to the specified date. Returns None. See Also Time:Set, To:Date. Notes Sets the DOS date. Date should be the result of the To:Date function. You can also specify a string value, but the format will need to conform to the last format you used in the To:Date function, or to MM/DD/YY if you have not specified another format. New programmers may note that JORF defaults to the American MM/DD/YY format, but is easily changed to suit European and Asian formats, as well as to create index values using YYYY/MM/DD format. Setting the DOS time and date does not always affect the computer's system clock. To permanently change the time and date on your computer, you may have to use a utility program. Network computers often get their date and time reset from the network file server. The JORF Manual (Shareware Disk Version) 110 Date:SetFmt Function Date:SetFmt ( FormatStructure ) Purpose Changes the default Month and Weekday names for Date:Str. Returns None. See Also Date:Str, Time:SetFmt. Notes The structure may be any structure with the elements specified below. The Element values are parsed and sorted in an internal static array. Changing the elements after setting them does not change the internal array until you call Date:SetFmt again. This function does not return any values, but sets up values for later use by Date:Str. The structure values are as follows: FormatStructure->Format | Default MM/DD/YY format FormatStructure->M1 | The name for January FormatStructure->M2 | The name for February . . . FormatStructure->M12 | The name for December FormatStructure->D1 | The name for Monday FormatStructure->D2 | The name for Tuesday . . . FormatStructure->D7 | The name for Sunday Chapter Five - JORF Functions 111 Example This program displays a text box showing the various time values, then switches to French (one of only two foreign languages I know well enough to know all the words, the other is Japanese, and you need a graphics screen for that). TimeTest:Start New Time Win:Add ("Time Test", 0, 0, 10, 40, Here) Time:Get (Time) Str:PutLine ("NDate: " +Time->NDate) Str:PutLine ("SDate: " +Time->SDate) Str:PutLine ("STime: " +Time->STime) Str:PutLine ("Switch to French") Time->M1="Janvier" Time->M2="Frevier" Time->M3="Mars" Time->M4="Avril" Time->M5="Mai" Time->M6="Jun" Time->M7="Juillet" Time->M8="Aout" Time->M9="Septembre" Time->M10="Octobre" Time->M11="Novembre" Time->M12="Decembre" Time->NDFormat = "dd.mm.yy" Time->SDFormat = "d m, y" Time->STFormat = "h.m.s a" Time:Get (Time) Str:PutLine ("NDate: " +Time->NDate) Str:PutLine ("SDate: " +Time->SDate) Str:PutLine ("STime: " +Time->STime) Win:Pause Return The JORF Manual (Shareware Disk Version) 112 Date:Str Function Date:Str ( Date, Format ) Purpose Formats the date according to format. You can also obtain month name, day of week, and other partial date information. Returns A formatted string. See Also Date:Get, Time:Str. Notes The specified date should be the result of the To:Date function that makes returns JORF pointer with an internal date value. (The internal value stores the date as a long integer value of the number of days since the mythical date January 1, 00. The format is a string saying how to format the date. The following are special character within the format string: Date Formatters s = String month Caps makes string upper case w = String weekday Caps makes string upper case n = Numeric weekday Caps is ignored m = Month Caps is ignored mm = Month, zero in front Caps is ignored d = Day Caps is ignored dd = Day, zero in front Caps is ignored y = Year Caps is ignored yy = Two digit year Caps is ignored yyyy = Four digit year Caps is ignored Any other characters are retained as-is. The following examples show how the date 10/13/92 would be formatted: Date:Str(Date,"MM/DD/YY") result "10/13/92" Date:Str(Date,"MM/DD") result "10/13" Date:Str(Date,"s d, yyyy") result "October 13, 1992" Date:Str(Date,"n-w" result "2-Tuesday" Date:Str(Date,"N-W") result "2-TUESDAY" You can easily change the table of month and weekday names to other languages using the Date:SetFmt function. If the format is omitted, the default format of "MM/DD/YY" is used. This default can be changed using Date:SetFmt. Chapter Five - JORF Functions 113 Date:Sub Function Date:Sub ( Date, Days, Months, Years ) Purpose Subtract the specified Days, Months, or Years from the Date. Returns A date. See Also Date:Add, Time:Sub. Notes This is a very specialized command that helps you calculate one month before, or 90 days before a date. This command does all the necessary calculations to account for month lengths and leap years. The JORF Manual (Shareware Disk Version) 114 Db:Append Function Db:Append ( FileName, Record ) Purpose Append Record to the end of FileName.. Returns Returns the record number of the new record appended to the file. If Record is a structure, the structure values are written See Also Db:Write. Notes In dBASE land, the only way to append is to use the command APPEND BLANK to append a blank record. In JORF land, you can append a filled record (structure) which simplifies the process of locking and adding a record to a dBASE file. If you APPEND BLANK, you must immediately lock the record before you set values and write the final record. When you append a filled record in the JORF style, locking is not required. (Locking is not required because the interpreter is automatically handling file locks. To append a record in a network environment, the entire file is locked, the record appended, and the file unlocked.) The Record is a JORF structure that contains fields with dBASE names. Each field is written to the file into the like named dBASE field. There must be a name correspondence between the JORF structure and the dBASE field name. Although you can add new fields to JORF structures very easily, you can only introduce new fields into a dBASE file by rewriting that entire file. Example jcm2dbf:Start | Conversion program for ASP.JCM to ASP.DBF | New (SrcFile,DstFile,Recno,Contact) Jorf:File("Contact.J",Here) | Read Class:Contact def SrcFile = "ASP.JCM" DstFile = "ASP.DBF" File:Del(DstFile) Db:Map (DstFile) | Need full mapping to create Name dbType:"C" Len:30 Title dbType:"C" Len:30 Company dbType:"C" Len:30 Address dbType:"C" Len:30 Chapter Five - JORF Functions 115 City dbType:"C" Len:20 State dbType:"C" Len:2 Zip dbType:"C" Len:10 Country dbType:"C" Len:20 Db:Create(DstFile) Jorf:File(SrcFile,Here) Win:Add("JCM to DBF File Converter",10, 10, 5, 35) Win:Msg("Press ESC to abort conversion.") Contact = Struct:Next("Contact", "FullName", Contact) While (Contact) ++Recno Move:To(2,2) Str:Put("Contact: {Recno}") Move:To(4,2) Str:Put("Name: {Str:Pad(Contact->FullName,30)}") Jcm2Dbf:Add(DstFile,Contact) If (Kbd:Hit) If (Kbd:Get=="Esc_Key") Break Contact = Struct:Next("Contact", "FullName", Contact) Return (Ok) Jcm2Dbf:Add(DstFile,Contact) New (Record,CommaPos) Record->Name = Contact->FullName Record->Company = Contact->Company CommaPos = Str:In(Contact->Addr2,",") If (CommaPos) Record->Address = Contact->Addr1 Record->City = Str:At(Contact->Addr2,1,CommaPos-1) Record->State= Word:At(Str:At(Contact->Addr2,CommaPos+1),1) Else Record->Address = Contact->Addr1+" "+Contact->Addr2 CommaPos = Str:In(Contact->Addr3,",") Record->City = Str:At(Contact->Addr3,1,CommaPos-1) Record->State= Word:At(Str:At(Contact->Addr3,CommaPos+1),1) Record->Zip = Contact->ZipCode Db:Append(DstFile,Record) Return (Ok) The JORF Manual (Shareware Disk Version) 116 Db:Close Function Db:Close ( FileName ) Purpose Explicit close for FileName.. Returns None. See Also Other File functions. Notes You do not have to close files in the JORF language. A Mapped file is closed according to the Level specified in the mapping. Files that are renamed or deleted are automatically closed prior to the renaming. This function exists because I might have forgotten a spot where a file should be closed before further handling. Chapter Five - JORF Functions 117 Db:Create Function Db:Create ( FileName ) Purpose Create a new dBASE file.. Returns Ok if file is created, Null if not. See Also File:Create. Notes If the file exists, it will be deleted. The file will then be created and the dBASE header written. If there are index (NTX) files declared in the mapping, they will also be deleted and created anew. dBASE files have a distinctive file header that is created with this command. You cannot write to a dBASE file without first creating the header. This is different than with ASCII delimited files which have no header and can be written without "Creating". The created file will be dBASE III, not dBASE II or dBASE IV format. Example See Db:Append. The JORF Manual (Shareware Disk Version) 118 Db:Delete Function Db:Delete ( FileName, Record ) Purpose Mark a record as "Deleted" Returns Ok if deleted, Null if record was already deleted or was not available to delete. See Also Db:Recall, Db:Lock, Other DB functions. Notes Before deleting, the Record must have been found, read and locked. The actual value for Record can be either the Recno integer value returned by Db:Seek, or the Structure value returned by Db:Lock. This command can then be used to "Delete" the record. In dBASE land, records are not eliminated when they are "Deleted". Instead, they are marked for deletion during the next PACK. Until the file is packed, the records will stay around and can be restored using Db:Recall at any time. Deleting a record will change the actions of Db:Seek, Db:Go and Db:Skip. These functions automatically skip right by "Deleted" records. You can change this action by setting the "Deleted" option on using Db:Set. Chapter Five - JORF Functions 119 Db:Go Function Db:Go ( Name, Pos ) Purpose Move the record pointer in a dBASE file. Returns Record number. Null if unsuccessful. See Also Db:Skip, Db:NtxOrd, Other DB functions. Notes Pos may be "Top" or "Bottom" to return the first or last record number of the file. Pos may also be any record number. The first record number is record number 1. The last record number can be obtained using Db:Go("Myfile.dbf", "Top"). The returned value is an integer value. If you are going to change the data, you should read it using Db:Lock. If you are reading the file for information or display only, you can red the record using Db:Read. This function is the equivalent of the dBASE "GO" and "GOTO" commands. The expression Db:Go("MyFile.dbf", "Bottom") returns the same value as the clipper LASTREC() function. The JORF Manual (Shareware Disk Version) 120 Db:Info Function Db:Info ( Name, InfoStructure ) Purpose Get information from the dBASE file header and current record. Returns InfoStructure, or Mem:Ptr if InfoStructure was null. See Also Other DB Functions. Notes Sets elements in Infostructure. That means that InfoStructure needs to have these elements declared, or must be a structure of the Jorf class that accept any elements. If you omit InfoStructure as I usually do, then the global value Mem:Ptr is used. The element values are: LastRec Last record number Found Whether last Db:Seek worked Eof File read or seek is at end of file Bof File read or seek is at beginning Deleted Current record is deleted Chapter Five - JORF Functions 121 Db:Lock Function Db:Lock ( Name, Record ) Purpose Lock a record in a dBASE file.. Returns Contents of record. Null if unsuccessful. See Also Db:Skip, Db:Goto, Other DB functions. Notes This command works just like DB:Read except that it locks the record before reading. The record remains locked until a Db:Write or Db:Unlock on the same record. The returned value is a Jorf structure that holds the dBASE record format. The structure is a member of the class declared in Db:Map. An additional member to that structure is the record number held in an element called Jrecno. The JORF Manual (Shareware Disk Version) 122 Db:Map Function Db:Map ( Name, Level, Class, Map ) Purpose Declare dBASE file, map fields for file creation.. Returns None. See Also Db:Create, Db:Read. Notes Map a file for use with Db:Read and Db:Create. The action of this command differs between reading an existing file and creating a new dBASE file. The parameter name is sets the file name. Once mapped, all reads and writes to that file will be influenced by the mapping. The parameter Class sets the structure type assigned to a record when it is read from the file. If no Class is declared, the JORF class will be used (Structures in the JORF class can accept any elements, there is no checking for legal element values). The last parameter is usually an indented section that contains the field mapping. The dBASE file format has a file header which declares the fields in the file. If you map an existing file, your field names will be ignored if they differ from the field names in the file header. For this reason, you must be sure to map existing files according to the correct names and field lengths. When you are reading a dBASE file, if there is any difference between the map and the header, the header takes precedence and the map values are ignored. When reading a dBASE file, it is common to omit the mapping entirely, and depend on the field definitions in the header. You can see this in the DBF2JCM.J example program. When you create a new dBASE file, you must map every field. Fields that you don't map will not be included in the new header of the file. You can see an example of this in the JCM2DBF.J example program. It is generally best to define the Len, dbName (the name of the field in the dBase file). You can also define the Dec for decimal point, and dtype for the dBase field type. If you do not define these the Chapter Five - JORF Functions 123 decimal places will default to zero, and the dbType will default to 'C' for the dBase Character type. When mapping a dBASE file, you can also map the NTX indexes for the file. JORF uses Clipper style NTX indexes, and not dBASE or FoxBASE style NDX indexes. The NTX format is quite different than NDX format, so don't try to rename the file and expect it to work. Contact:CvtDBASE New (Contact:Contact,FName,Counter) FName="MyFile.Dat" | Add a window to show what is happening Win:Add ("Reading {FName}", 0, 0, 10, 76, Here) Db:Map (Fname,Here,"DBASE","Contact") Company Len:40 dbType:"C" dbName:"COMPANY" Addr1 Len:40 dbType:"C" dbName:"ADDR1" Addr2 Len:40 dbType:"C" dbName:"ADDR2" Addr3 Len:40 dbType:"C" dbName:"CITSTZ" Junk Len:20 dbType:"C" dbName:"CODES" FullName Len:40 dbType:"C" dbName:"CONTACT" Zip Len:10 dbType:"C" dbName:"ZIP" For (Counter = 1 thru Db:Go(Fname,"Bottom")) Contact=Db:Read(Fname,Counter) Str:Put (Str:Pad(Counter,4)) Str:Put (Str:Pad(Contact->Company,30)) Str:Put (Str:Pad(Contact->FullName,30)) Str:PutLine Jorf:Write(Contact) Return Ok To define an index, your map line must definition must begin with the key expression "NTX" followed by a colon and the name of the index. You only need the file name, the path is assumed to be the same directory as the base dBASE file. The JORF interpreter needs enough information to interpret the index values. When using NTX indexes in JORF, it is best to declare the index length and constructor string. If you omit this information, the JORF interpreter will try to obtain the information from the index header. An index constructor string is maintained in each NTX file header. If the index key is a simple field, then the string is simply the field name. If the index key contains any dBASE expressions, however, you must tell the interpreter how to construct the equivalent key using JORF expressions. Examples are: The JORF Manual (Shareware Disk Version) 124 dBASE Key JORF Key Name Name | Same Name+Zip Name+Zip | Same Dtos(StDate) Date:Str(StDate,"YYYYMMDD") | Different The key thing to remember is that the JORF language is different from the dBASE language, and you must translate any complex key expression to the appropriate JORF language expressions. Chapter Five - JORF Functions 125 Db:NtxOrd Function Db:NtxOrd ( Name, NtxNumber ) Purpose Switch indexes in an open file.. Returns None. See Also Db:Skip. Notes If you have declared indexes using Db:Map, you can use this function to select which index to use for the next Db:Skip. The first declared index is 1. If you indicate an NtxNumber of zero, no index is declared and Db:Skip will be based on the natural order of the records. The JORF Manual (Shareware Disk Version) 126 Db:Pack Function Db:Pack ( Name, Showit ) Purpose Pack a dBASE file, DBT text file and re-write NTX indexes. Returns False if File could not be locked for packing. Otherwise Ok. See Also Db:Map. Notes While most JORF dBASE commands work like their dBASE cousins, this one is an improvement over the dBASE PACK function. In JORF, this command rewrites the entire file, insuring a complete rewrite before the original file is deleted. For that reason, enough disk space is required to hold the entire new copy of the file. After the file is rewritten and renamed, it is automatically reindexed based on the declared indexes. Programmers not familiar with dBASE files should note: In dBASE-Land, records are not really deleted. When you delete a record using Db:Del, that record continues to take space in the file until the file is packed. The pack function recovers the space used by the record because it rewrites only un-deleted records in the new version of the file. For this reason, all dBASE programs feature pack functions prominently, because without them the files grow endlessly. Programmers familiar with DBT files may note that JORF uses DBT files just like Clipper, reusing the existing space if possible, but allocating new blocks if the memo field grows beyond the current 512 block boundary. Previously used memo blocks continue to take space until a file is packed. If Showit is True, the Db:Pack function will display a status box while writing and re-indexing the file. Example See Db:Map. Chapter Five - JORF Functions 127 Db:Read Function Db:Read ( FileName, Recno ) Purpose Read a record from a dBASE III file.. Returns The record that was read. See Also Db:Seek. Db:Goto, Db:Lock. Other DB Functions. Notes The Db:Read function is used to read a record obtained using one of the record pointer moving functions Db:Seek, Db:Skip and Db:Goto. If Recno is omitted, then the record number returned by these functions will be used. In dBASE land, this is called the "Current" record number. In JORF land, structures are known more by their pointer nature and more than one structure of the same class may be "Current". The JORF Manual (Shareware Disk Version) 128 Db:Recall Function Db:Recall ( Name, Record ) Purpose Un-mark a "Deleted" record. Returns Ok if record was properly unmarked. Null if record was not previously "Deleted". See Also Db:Del, Db:Lock, Other DB functions. Notes You will have to set "Deleted" to True just to seek or goto a "Deleted" record. Once you have, you can "Un-delete" the record with this function. This function is the equivalent of the dBASE RECALL command. Chapter Five - JORF Functions 129 Db:Seek Function Db:Seek ( FileName, Keyvalue ) Purpose Searches the index for key value. Returns Record number of record. Null if match was not found.. See Also Db:Skip, Db:NtxOrd, Other DB functions. Notes Searches for an index match to Keyvalue. To seek, you must have declared indexes and be set to the correct index using Db:NtxOrd. If you attempt to seek without a valid index in use, Null will be returned. The Db:Set function can change the nature of the seek. If you set "Deleted" to TRUE, then this function may return the record number of a deleted record. If "SoftSeek" is true then this function may return the next higher record if the exact Keyvalue is not found. The returned value is an integer record number. If you are going to change the record, use Db:Lock to read it. If you are just looking at the data, use Db:Read. This function is the equivalent of the dBASE "SEEK" command. Example See Db:Read The JORF Manual (Shareware Disk Version) 130 Db:Set Function Db:Set ( Name, Option, Value ) Purpose Do dBASE style "Set" functions that influence DB commands. Returns Prior setting. See Also Db:Info, Other DB Functions. Notes The dBASE language has numerous global settings that are declared using the dBASE SET function. In JORF, two settings were needed to implement the most rudimentary dBASE capability. More SET commands may be added later. The current Options that may be set are: "Deleted" True or False Default False "SoftSeek" True or False Default False When "Deleted" is True, functions like Db:Go and Db:Seek will go to and seek to deleted records as if they were not deleted. A deleted record in dBASE is not really deleted until you PACK the file - so you can freely set "Deleted" False and then read and undelete the record. When "SoftSeek" is True, the Db:Seek function will seek to the next higher key value in the file. If it is False, Db:Seek will return null if the exact key (to the length of the key) is not found. SoftSeek is usually False for relational look ups (Key look-ups into related data bases), but true for any screen display or user oriented look-up, so the operator may see close matches even after misspelling the key value. Chapter Five - JORF Functions 131 Db:Skip Function Db:Skip ( Name, Record, SkipBy ) Purpose Move the record pointer in a dBASE file. Returns Record number of next record. Null if unsuccessful. See Also Db:Go, Db:NtxOrd, Other DB functions. Notes This function is used to traverse records in a data base. Normally SkipBy is 1 (this is the default if it is omitted) and this function returns the next record in the file. If the end of file is reached, then the return value will be Null. You can also declare a SkipBy value of -1 (negative one) to read the previous record in the file. You can skip though the file by any number of records, positive or negative. The "Next" record is influenced by whether NTX indexes are declared and which one is in use. If there is an active index, the next record will be chosen according to the key value. If there are no active indexes, or if Db:NtxOrd is zero, then the next record will be the next physical record in the dBASE file. If Record is null and SkipBy is positive, the first record is read just as if you used Db:Go("MyFile.DBF","Top"). If the SkipBy is negative, the last record is read as if you started with "Bottom". The return value is the record as read from the disk. If you are going to change the record, you should lock the record and use the return value from Db:Lock to get the most recent version of the record. Example See Db:Read The JORF Manual (Shareware Disk Version) 132 Db:Unlock Function Db:Unlock ( Name, Record ) Purpose Unlock a record in a dBASE file.. Returns Ok if record was locked. Null if not locked. See Also Db:Lock, Db:Write, Other DB functions. Notes When you are using a record in a multi-user environment you must lock the record while it is being changed. To lock a record, use Db:Lock. To write the record and unlock it, use Db:Write. But if the operator aborts the edit, you need to unlock the record and restore the original values that the operator may have changed. That is the purpose of this function. This function re-reads the record and unlocks it in that order. This is the proper process for handling an aborted edit of a record on a multiuser system. To find the appropriate spot in the file, the Record must have a valid Jrecno element. This element is automatically created by any of the DB functions that read records. Example See Db:Read Chapter Five - JORF Functions 133 Db:Write Function Db:Write ( Name, Record ) Purpose Write a Record to a disk file. Returns None. See Also Db:Append. Notes Writes an existing record to the file, unlocks the record. To write a new record, you must use Db:Append. Unlike dBASE, which writes to the "Current" record number (The last value returned by a SEEK or GO command), JORF stores the record number in the record structure. When a record is written, it will be written to the record where it was read, regardless of whether the "Current" record has since changed. JORF allows you to have more than one record active at a time, even in dBASE files. The Db:Write function defines a physical write operation like the dBASE COMMIT function. There is no need to "Replace With" in the JORF language as there to set fields in dBASE. The JORF Manual (Shareware Disk Version) 134 DirList:GetFile Function DirList:GetFile ( Wildcard, ExclusionLIst ) Purpose Display "DialogDirList" box for file name.. Returns File name selected, or Null if Cancelled. See Also DirList.J source file. Notes This is a JORF language function that has become a permanent part of the interpreter. The source code to this function is entirely contained in the DIRLIST.J source file. This function asks for file name and path, while displaying selection lists for both. The display is designed to look somewhat like Windows' DlgDirList box, but does not use DlgdirList even under MS-WIndows. The WildCard and ExclusionList are used as document in the Arr:Dir function. The wildcard is used to choose files to display, and the exclusion list insures that inappropriate files are not displayed. Example The TEXTEDIT.J sample program makes good use of the DirList:GetFile function. Chapter Five - JORF Functions 135 Event:Add Function Event:Add ( Class, Type, Level ) Purpose Add an Event Class. Returns None. See Also Event:Do, Event:Del. Notes The Event system is a way of performing a method in response to an event that occurs during normal processing. This is a way of saying "If such and such happens while this program runs, then do this to take care of it". Three types of events set up in the JORF system are the key, trace and error events. Key events occur whenever the operator enters a keystroke. This allows the system to evaluate the key and to respond appropriately. Trace events are used for trace mode debugging, and will be executed at particular times during while a method is begin interpreted. Error events occurs when is an error. It is automatically called, in hopes that error recovery is possible. Of these, Key events are by far the most common. Event:Add adds a new Class name to the event stack for event Type tied to the current program Level. The event classes form a stack so that the new entry is simply the top one of many that might be used. The level lets the system know what method is declaring the new class, and will automatically clear this entry when that method is completed. The types Error and Key are already used by JORF for error and keystroke handling. Other types may be any name later used by Event:Do. When events are performed, the event stack is searched from top (most recent) to bottom. When a valid method is found, it is executed. If the method returns any value, the search is completed. If the method returns null, the search is continued down the event stack. A null class can be used to block the search function from going any lower on the event stack. If this is not complicated enough, there is a "Hot" event system. If you declare an event with a Level of zero, then you create a hot event. Once declared, Hot The JORF Manual (Shareware Disk Version) 136 events are permanent. Normal events are cleared when the method that declared them is ended. Hot events are checked after the first event level, but before the "Else" clause is checked. Hot events give a way to set default key values, like Alt-X for exit in the debugger. The Level value should always be Here. Chapter Five - JORF Functions 137 Event:Del Function Event:Del ( Type ) Purpose Deletes the last event Class for event function of designated Type. Returns None. See Also Event:Add, Event:Do. Notes This function is rarely used because usually the Event Classes are deleted automatically when the method that creates them is ended. The sole use of this command is to try to circumvent that system. You should try to work with the automatic delete system, because it is more robust. However, if you insist, this function will delete the last event class entry with this Type. The JORF Manual (Shareware Disk Version) 138 Event:Do Function Event:Do ( Method, Type ) Purpose Performs an event. Returns If an event method is found, executed and returns a value, then that value is returned by Event:Do. See Also Event:Add, Event:Del. Notes The most confusing thing here is to figure out how the system is creating the method name to call when an event is performed. The inclination is to look at this command and assume that the method will perform Type:Method. Instead, the type is used to down the event stack for the appropriate Class that was set using Event:Add. It is this class used to do Class:Method. Each class of the correct type is attempted. If that fails, then the system looks for an Else method for that class. The Else methods are a default method for the event type. If this is not found, the system looks down the event stack to the next lower class of the correct Type. This system allows a layering of event actions. It was designed primarily for keystroke handling, where a certain screen may need to reassign only four keys, while maintaining the functions of other keys. Many key handling systems remap all keys. This is unwieldy if only four keys have different definition. But, for events other than keystrokes, this overlay ability may be too complicated and unnecessary. Liberal use of the Else method is recommended to avoid the stack search and resulting confusion. Special Notes for Key Events For text entry, data entry and menu selection, keystrokes from the operator are translated by the system using the KeyClass stack. The names in the stack interpret the current keystroke. The keystroke is converted to a string value and the method called that corresponds to the appropriate class and value. For instance, pressing the Escape key with a KeyClass of "MenuKey" will invoke the method MenuKey:Escape_Key. Chapter Five - JORF Functions 139 Normal letters have "_Key" appended, so hitting B will return "B_Key". Alternate and Control keys have a prefix appended to create "Alt_B_Key" and "Ctrl_B_Key". Special keys return special values like "Home_Key", "F1_Key" and "Ctrl_Right_Arrow_Key". A list of special key values is in Appendix B. Special notes for Error Events Error events are called like the key events using the error number as the method name. Inside an error event several values are set using Mem:Ptr: Mem:Ptr->ErrNum | JORF Error Number Mem:Ptr->ErrDOS | Last DOS error number Mem:Ptr->ErrLine | Line that was executing when | error occurred Mem:Ptr->ErrMsg | Text of the error message Fatal errors do not call the event system. Usually these errors show that something has happened that will not allow further action in The JORF Language interpreter, and the program must halt immediately before data integrity can be lost. When an error occurs while processing another error, the second error is considered fatal. The JORF Manual (Shareware Disk Version) 140 False Function False Purpose Used to test for Logical False. Returns Null. See Also True. Notes Most programming language express results of logical equations as zero to indicate False, and one to indicate True. These values are called Boolean values. This function was created in the interest of program clarity. It simply returns Null. Due to the automatic type conversions inherent to Jorf Pointers, this is exactly the same as the integer zero. Chapter Five - JORF Functions 141 File:Append Function File:Append ( FileName, Line ) Purpose Append Line to the end of FileName.. Returns Record Number. See Also File:Write. Notes Append a line to a text file, or a record to a formatted file. If you append to a mapped file, this function appends line or if null, appends a blank record to the end of the file. The function returns the new record number. If you append to an unmapped file, a text line is added followed by a Carriage Return-Line Feed (CR-LF) pair. If Line is null, just the CR-LF is written to file. The return value is the byte position of the new line in the file. When used with DLM, SDF and FIXED mapping formats, this function allows you to append records as desired to the file. You need not specify Line. WIthout it, the effect is exactly like the dBASE "APPEND BLANK" command. This function is specifically written to make dBASE language programmers comfortable. The JORF Manual (Shareware Disk Version) 142 File:Backup Function File:Backup ( FileName ) Purpose Renames FileName to have an extension of .BAK. Returns None. See Also Other File functions. Notes This function makes a backup of a file, presumably before calling a command that might overwrite the file like File:Save. Example See Arr:Pick. Chapter Five - JORF Functions 143 File:ChDir Function File:ChDir ( NewDir ) Purpose Change current directory or Return current directory. Returns If NewDir is Null, returns current Directory. If present, returns Ok if successful, False if not. See Also Other File functions. Notes This function is the equivalent of the DOS ChDir or CD command. Like ChDir, it can be used two ways. By itself, it simply returns the disk and path of the current working directory. If followed by a new path, it changes to that path. Unlike DOS ChDir, File:ChDir will change drives as well as paths. If you say CD D:\ while logged to drive C: in DOS, you only change the default directory on D:.. If you say File:ChDir("D:\") in the JORF language, you will be moved to drive D:, root directory.. The JORF Manual (Shareware Disk Version) 144 File:Close Function File:Close ( FileName ) Purpose Explicit close for FileName.. Returns None. See Also Other File functions. Notes You do not have to close files in the JORF language. An unmapped file is closed automatically when the method that uses that file is ended. A Mapped file is closed according to the Level specified in the mapping. Files that are renamed or deleted are automatically closed prior to the renaming. This function exists only for the rare exception where an explicit close is desired for the purposes of other operations in the current routine. Chapter Five - JORF Functions 145 File:Copy Function File:Copy ( OldName, NewName ) Purpose Copies file from OldName to NewName. Returns Ok if copied, Null if file not found or unable to copy.. See Also Other File functions. Notes This function copies a file. Like DOS, this function will erase the an existing files in order to re-use the name. The JORF Manual (Shareware Disk Version) 146 File:Del Function File:Del ( Name ) Purpose Delete a file from disk. Returns Ok if file is deleted, Null if not. See Also Other File functions. Notes All information in the file will be destroyed. If the file is currently opened, it will be closed. Does not give an error if the file is absent. Chapter Five - JORF Functions 147 File:Exist Function File:Exist ( FileName Command ) Purpose Checks file existence, read permission or write permission. Returns True if file exists, can be read, or can be opened for writing. Returns False if not. See Also Other File functions. Notes This function is the JORF language equivalent to the UNIX C language access() function. Command may be Null or "Exist" to check for existence. If Command is null or absent, the existence of the file is checked. If the file exists, this function returns True. If the file does not exist, the function returns False. Command may be "Read" to check for network read access to the file. If the file exists and can be read, this function returns True. If the file does not exist, or cannot be opened by the current operator for reading, the function returns False. Command may be "Write" to check for network write access to the file. If the file exists and can be opened for writing by the current operator, the function returns True. If the file does not exist, or cannot be opened for writing, the function returns False. This function used to be named File:Access. The name was changed in version 2.1 of the JORF Interpreter. The name was changed to be more indicative of the most common use of this function. Example See Event:Add. The JORF Manual (Shareware Disk Version) 148 File:Len Function File:Len ( Name ) Purpose Get Length of file on disk. Returns Length of file in Bytes. See Also Other File functions. Notes Returns the current length of the file in bytes. If the file is not found, the length will be 0, the same as if the file is empty. Example See File:Read Chapter Five - JORF Functions 149 File:Load Function File:Load ( Name ) Purpose Load a text file into a text pointer. Returns Text pointer. See Also File:Save, File:Read. Notes Loads a text file wholesale into swap storage, which is much faster than trying to read it line-by-line and adding the lines using Text:Add. Use this for text file editors like the JORF.INI editor. Example See Event:Add. The JORF Manual (Shareware Disk Version) 150 File:Map Function File:Map ( Name, Level, Type, Class, Map ) Purpose Map a file in a foreign format for reading and writing. Returns None. See Also File:Read, File:Write. Notes Map a file for use with File:Read and File:Write. When you map a file you map structures and fields to write different file types. The parameter name is sets the file name. Once mapped, all reads and writes to that file will be influenced by the mapping. The parameter type sets the type of the file to be mapped. Available types are DLM, SDF, FIXED, and DBASE. DLM stands for comma delimited. This is the most common type. Fields are quoted and separated by commas. There is a fixed number of fields per records. Records end in a carriage return line feed pair. FIXED stands for fixed length record format. This is the most common proprietary format. SDF stands for system data format. This type is very close to FIXED but records in an SDF file must end in a carriage return-line feed pair. DBASE stands for DBASE III format files. Normally you use the special DB:Map function to map dBASE files. This function automatically calls DB:Map if you want to use this function for consistency. . The last parameter is usually an indented section that contains the field mapping. Each line of this section relates to a single field in the mapping. You must map every field, even if you don't want the data. You can map several fields into one so if you create a field that is called "junk" and put all extra fields into it you will fulfil the mapping requirement. Chapter Five - JORF Functions 151 The simplest mapping is for a delimited file, where you merely have to list the field names. Contact:CvtDlm New (Contact:Contact,FName,Counter) FName="MyFile.Dat" | Add a window to show what is happening Win:Add ("Reading {FName}", 0, 0, 10, 76, Here) File:Map (Fname,Here,"DLM","Contact") Company Addr1 Addr2 Addr3 Junk FullName Zip Junk While (File:Ok(Fname)) Contact=File:Read(Fname,Here) ++Counter If (Contact->FullName==Null) Contact->FullName = Contact->Company | Put record stuff in window to show what is happening Str:Put (Str:Pad(Counter,4)) Str:Put (Str:Pad(Contact->Company,30)) Str:Put (Str:Pad(Contact->FullName,30)) Str:PutLine Jorf:Write(Contact) Return Ok The JORF Manual (Shareware Disk Version) 152 The next simplest is for a FIXED or SDF file. These formats are very similar because they are both fixed length format. The only difference is that you must include the record length when you read a FIXED length file. You don't need a record length when you read a DLM file. In a FIXED length file, if you map wrong, your fields will be split. If you really map wrong, excess fields are ignored and not enough fields will result in blank fields in the JORF structure. In a fixed length format, you must specify the length of each field. Contact:CvtFIXED New (Contact:Contact,FName,Counter) FName="MyFile.Dat" | Add a window to show what is happening Win:Add ("Reading {FName}", 0, 0, 10, 76, Here) File:Map (Fname,Here,"FIXED","Contact") Company Len:40 Addr1 Len:40 Addr2 Len:40 Addr3 Len:40 Junk Len:20 FullName Len:40 Zip Len:10 Junk Len:2 While (File:Ok(Fname)) Contact=File:Read(Fname,Here,232) | Record length is 232 ++Counter If (Contact->FullName==Null) Contact->FullName = Contact->Company | Put record stuff in window to show what is happening Str:Put (Str:Pad(Counter,4)) Str:Put (Str:Pad(Contact->Company,30)) Str:Put (Str:Pad(Contact->FullName,30)) Str:PutLine Jorf:Write(Contact) Return Ok The last format is for dBase files, and is handled in detail in the reference section for DB:Map. If you are want to use the dBASE field names, you hardly need map the file at all. If you want to write NTX indexes, you will have to declare them in the mapping section however. If you are creating a new file, or want to change the field names in the file, you must map each field. Chapter Five - JORF Functions 153 dBASE files carry their mapping in the file header. If your map does not match the actual file map, then not all of your fields will have a proper value. Your fields may not come into effect until you create or rebuild the file according to your specified data base fields. It is generally best to define the Len, dName (the name of the field in the dBase file). You can also define the Dec for decimal point, and dtype for the dBase field type. If you do not define these the decimal places will default to zero, and the dType will default to 'C' for the dBase Character type. Contact:CvtDBASE New (Contact:Contact,FName,Counter) FName="MyFile.Dat" | Add a window to show what is happening Win:Add ("Reading {FName}", 0, 0, 10, 76, Here) File:Map (Fname,Here,"DBASE","Contact") Company Len:40 dName:COMPANY Addr1 Len:40 dName:ADDR1 Addr2 Len:40 dName:ADDR2 Addr3 Len:40 dName:CITSTZ Junk Len:20 dName:CODES FullName Len:40 dName:CONTACT Zip Len:10 dName:ZIP While (File:Ok(Fname)) Contact=File:Read(Fname,Here) | No record length needed ++Counter If (Contact->FullName==Null) Contact->FullName = Contact->Company | Put record stuff in window to show what is happening Str:Put (Str:Pad(Counter,4)) Str:Put (Str:Pad(Contact->Company,30)) Str:Put (Str:Pad(Contact->FullName,30)) Str:PutLine Jorf:Write(Contact) Return Ok The JORF Manual (Shareware Disk Version) 154 File:MoveTo Function File:MoveTo ( Name, Position ) Purpose Go to the front or back of a file. Returns None. See Also File:Read. Notes Can be used to "Rewind" a file to the beginning, or to "Append" after rewinding. Position must be the string value "Beginning" or "End". Only the first letter is used, but three letters ("Beg" and "End") are recommended for clarity. Chapter Five - JORF Functions 155 File:Ok Function File:Ok Purpose Check for End of File while reading. Returns False if End of File has been reached while reading, otherwise True. See Also File:Read, File:Len. Notes This command is used in conjunction with File:Read to create a loop that ends when the last line or record of the file has been read. This test is the opposite of the normal C function eof(), because I like testing "If Ok" rather than "If Not EOF". If a file is not yet open, it is still "Ok". This fact enables you to make cleaner While loops. Example See File:Map. The JORF Manual (Shareware Disk Version) 156 File:Print Function File:Print ( File Printer Flags ) Purpose Print a File on a printer. Returns None. See Also Arr:Printers Notes Printer output is always a chore, and never gets any easier. Even after IBM creates the great parallel interface, that is standard and needs no set up, companies like Hewlett Packard create printers like the original Laserjet that only support serial output. The adjustment to MS-Windows has caused the Str:Print and Char:Print commands to be eliminated, and this command put in their place. Windows support for character-by-character output to printers was just too slow to be tolerable. MS-DOS programmers may also note that Windows requires that printing under Windows is done by page, and that only full pages may be printed. This command prints File to the designated printer. The printer is usually the output from the Jorf:Printer function. The file can also be SCREEN, FILE, PRN, AUX, LPT1, LPT2, COM1, or COM2 indicate screen, print to file, default printer, auxiliary, line printer one and two and serial printer one and two respectively. The different printing mechanisms are distinct. The of the printer options, the easiest and most robust is to print to PRN, the default printer. To test to see if your printer is working, use the DOS PRINT command to print a small file. If it prints normally, you should have no problems using Str:Print "PRN" String. DOS lets you redirect PRN to any printer, including serial printers. The next most robust is LPT1 and LPT2. These use a different BIOS call than PRN so they may not work even when PRN works just fine. These commands send output to parallel printers. Parallel printers may be identified by having a thick cable and a bigger-than-normal connector on the printer end of the cable. The most difficult type of printer to use is the serial printer. Serial ports COM1 and COM2 are general Chapter Five - JORF Functions 157 communications ports, and the RS232 standard is not as standard as I would like. As always, try to get your printer to work using the DOS Print command, and not with the JORF interpreter. If you cannot print from DOS, I guarantee that you will not print from JORF. You cannot set the speed of the port in the JORF interpreter. Instead, use the DOS MODE command. Most printers default to 9600 baud, 8 bits, no parity, one stop bit, that can be set with the following command: C>Mode Com1:9600,n,8,1,p If this works, put it in your AUTOEXEC.BAT file so it sets the port up every time the computer starts. If this doesn't work, check your printer manual to see that the printer and the serial port mode agree. In theory, the File:Print supports COM1 to COM9 and LPT1 to LPT9. However, DOS and Windows your BIOS probably don't. Windows is especially notorious for not handling COM3 and COM4 correctly, even when they work under DOS. JORF does not yet support any printer control codes, even under windows. Your file will be printed using the default font on your printer. Page breaks are respected, and even if your document does not end with a page break, a formfeed will be added. The Flags parameter is usually omitted. The only valid flag value is "N" for No-Eject last page. Normally the last page of the report is ejected, but this may not be desired for when printing mailing labels or other continuous forms. Other flags are anticipated. The JORF Manual (Shareware Disk Version) 158 Example This fragment is from Contact.J. Contact:MergeLetter New (Dest,Letter,CurrContact) Time:Get(Mem:Ptr) Letter=File:Load(Contact:GetLetter) If (Letter!=Null) Dest=Jorf:Printer() If (Dest) CurrContact=Mem:Ptr->Contact Mem:Ptr->Contact=Null Win:Add("Printing") Printing . . . Rep:Add ("Merge Letter", 5, 5, 60, 75,Here) Header:"" Row:1 Next:"Contact:NextRecord('Next')" Text:"Letter" File:Print("JREPORT.LST",Dest) Mem:Ptr->Contact=CurrContact Return (Ok) Chapter Five - JORF Functions 159 File:Read Function File:Read ( Name, Size, Offset ) Purpose Read a line of text or a record from a disk file. Returns The line or record that was read. See Also Other File Functions. Notes The File:Read and File:Write commands handle both ASCII and binary files without making any distinction between them. Name is required. Normally this command reads the next line of input terminated by the line feed character. The line feed character is eliminated from the input text. (In prior versions there was a parameter Level that is now no longer used. This change is not upward compatible and you must be sure that any programs for JORF versions prior to 2.1 are corrected.) If Size is specified then the a binary file read will take place where the record is Size bytes. Offset is specified then read will take place at that position offset. If not specified, the current file position will be used. You can return to the beginning of the file using File:MoveTo and can go to a byte position using File:Read with a record size of 1. Reading a file in comma delimited, fixed length and dBase format may be influenced by using the File:Map function. Example See Arr:Sort The JORF Manual (Shareware Disk Version) 160 File:Rename Function File:Rename ( OldName, NewName ) Purpose Renames OldName to NewName. Returns Ok if renamed, Null if file not found or unable to rename.. See Also Other File functions. Notes This function renames a file. Unlike DOS, this function will erase the an existing files in order to re-use the name. (In DOS, you cannot rename a file to an existing name). Example See Jorf:Ini. Chapter Five - JORF Functions 161 File:Save Function File:Save ( Name, Text ) Purpose Save text to a file. Returns None. See Also File:Load, File:Backup. Notes Saves a text file wholesale from swap storage, which is much faster than trying to write it line-by-line. Does not automatically make a backup so if you want one, use File:Backup. Example see Jorf:Write. The JORF Manual (Shareware Disk Version) 162 File:Write Function File:Write ( Name, Line, Size, Offset ) Purpose Write a Record to a disk file. Returns None. See Also Other File Commands. Notes Writes to the file for sequential or binary output. Name is required. (In prior versions there was a parameter Level that is now no longer used. This change is not upward compatible and you must be sure that any programs for JORF versions prior to 2.1 are corrected.) The file is always opened for update and the file pointer is placed at the beginning of the file. If you want to create a file, use File:Del to insure that the file is new. If you want to append data to the file, use File:MoveTo to change the file pointer, or File:Append to write directly to the last record position in the file. If Size is specified then Line will be null padded or truncated to the length specified then written to file. If Offset is specified then write will take place at that position offset. If not specified, a carriage return line feed pair is appended and the line is written in sequential mode. If Line is omitted or Null, and Size is zero the file will be handled as a text file and a carriage return - line feed pair will be appended to the file. The only way to write files without appending the CR-LF characters is to write them using the Size parameter. You can move to any byte position in a file by using File:Read with a record size of 1. You can move to the front or back of a file using File:MoveTo. Reading a file in comma delimited, fixed length and dBase format may be influenced by using the File:Map function. Example See DirList:GetFile for an example of writing a text file. Chapter Five - JORF Functions 163 For/Thru/Step Function For/Thru/Step Purpose A counting loop. Returns None. See Also While. Notes A specialized loop based on a numeric counter. Based on the BASIC For/Next loop, there is no need for a "Next" here because indentation makes the loop structure clear. For ( Value = 1 Thru 10 Step 2 ) Lines to do The BASIC key word "To" has been changed to "Thru" for the sake of accuracy. If computers are literal, the commands must also be literal. (The BASIC loop uses "To" but actually goes "Through" the value, a bit of inaccuracy that is not appropriate for literal minded computers.) You can use Break to break out of a For loop, or Continue to continue the loop, just like a While loop. If the ending value is a function result or mathematical equation, it is calculated only as the loop is entered, and not for each iteration of the loop. Example For loops always replace While loops as this example shows: For Loop While loop equivalent. OnetoTen:Start OnetoTen:Start New (Num) New (Num) Win:Add ("One to Ten") Win:Add ("One to Ten") | Num = 1 For (Num = 1 thru 10) While (Num <= 10) Str:PutLine (Num) Str:PutLine (Num) | ++Num Return (Ok) Return (Ok) In this case, the first time the loop is entered, Num is initialized to 1. It is the incremented by one, The JORF Manual (Shareware Disk Version) 164 until it is greater than 10. The loop then continues. reaches 10. You can see in the above example that the initializer and ending condition are in a single line, and the incrementer is implied, so the For loop is contained in a single line. The while loop takes the usual three lines to specify the initializer, ending condition and incrementer. There is one variation on the For loop, and that is to have it increment by something other than 1. For instance, maybe we want to count by threes, or count backwards from 10 to 1. To do this, simply add a "Step" command to the For loop: For Loop While loop equivalent. ByTwos:Start ByTwos:Start New (Num) New (Num) Win:Add ("One to Ten") Win:Add ("One to Ten") | Num = 1 For (Num = 1 thru 10 Step 2) While (Num <= 10) Str:PutLine (Num) Str:PutLine (Num) | Num = Num + 2 Return (Ok) Return (Ok) For Loop While loop equivalent. TentoOne:Start TentoOne:Start New (Num) New (Num) Win:Add ("One to Ten") Win:Add ("One to Ten") | Num = 10 For (Num = 1 thru 10 Step -1) While (Num >= 1) Str:PutLine (Num) Str:PutLine (Num) | --Num Return (Ok) Return (Ok) Chapter Five - JORF Functions 165 Here Function Here Purpose Return the current method location. Returns The current method location. See Also Win:Add, Event:Add. Notes Returns the current stack position as an unsigned integer. When the interpreter is started, this value is 1, and each nested method increases the level by one. The highest stack level that can be expressed this way is 65,535 (Hexadecimal ffff). This command provides a simple way of marking windows, files, and events so The JORF Interpreter can automatically delete them when you are done. The complete display method for a window may be nested several levels deep. Usually, the call to the method uses Here, and the various methods pass that value as a parameter called Level. It is not kosher to manipulate this value by adding or subtracting from it. Doing so will confuse the automatic clearing mechanism, which may clear too little or too much. Example See Jorf:Write. The JORF Manual (Shareware Disk Version) 166 If/Else Function If/Else Purpose A conditional branch. Returns None. See Also Switch, While. Notes Tests the value of a parameter and executes indented code sections based on that value. If ( TestValue ) Lines to do if True Else Lines to do if False The If function tests a condition and branches based on that condition. If the condition is true, then the indented section is performed. If the condition is not true, then program flow skips to the Else command. If (A=2) B=4 Else B=6 The condition does not have to be a logical comparison. A single variable may be used instead, in which case it will be True if it has any value, and False if it is null. If (Word) Str:Put (Word) Else Str:Put ("(Null)") The condition may be a complex comparison involving both logical and value elements If (Counter > 3 && Word) Str:Put ("Counter too large for {Word}") Else ++Counter Parentheses around the If test is optional. Chapter Five - JORF Functions 167 Jorf:Cls Function Jorf:Cls Purpose Clear the DOS Screen. Does nothing under Windows. Returns None. Both the DOS and the Windows versions of JORF place windows on the previous screen contents. Although this is traditional for Windows programs, most DOS programs clear the screen instead. To allow you to follow this custom, this command will clear the screen in the DOS version of JORF. If you clear the screen while some windows have been displayed, you will get some really weird results when those windows are later "erased". Be sure there are no windows displayed when you clear the screen. The JORF Manual (Shareware Disk Version) 168 Jorf:Del Function Jorf:Del ( Item ) Purpose Deletes data. Returns None. See Also Jorf:Write. Notes Deletes the data associated with Item. This may be a Structure or block of text. To delete a method use Method:Del. The system automatically saves data when it is indexed to the Rule system, and when you use the Jorf:Copy and Jorf:Write commands. The Data is a permanent part of the data file until it is deleted with this function. There is no harm in doing a precautionary delete for item that has not been saved. Chapter Five - JORF Functions 169 Jorf:Do Function Jorf:Do ( MethodName ) Purpose Interpret a string as a command. Returns Return value of command. See Also Event:Do. Notes Interprets a string as if it were a command. This is used to execute a command that has been assembled using string values. This ability allows the assembly and execution of new commands and methods by a program which then immediately calls them. The JORF Manual (Shareware Disk Version) 170 Jorf:Dup Function Jorf:Dup ( Item ) Purpose Make a copy of a Text or Structure. Returns A duplicate copy of Item. See Also Jorf:Del. Notes This command is used to create a duplicate copy of Item so you can change it without affecting the original. This command will automatically write both copies to the current project file, so if they are temporary, they must be deleted using Jorf:Del. Example See Jorf:Del. Chapter Five - JORF Functions 171 Jorf:Exit Function Jorf:Exit ( Status, Message, Command ) Purpose Exit from The JORF Interpreter. Returns Does not return. See Also Jorf:System. Notes Flushes disk caches and memory items, closes all files and windows, exits to the operating system. This function is called involuntarily when a fatal error occurs. If Status has a value, this is returned to the operating system. Under windows 3.1 the program return value is not supported but maybe Mr. Microsoft will fix this someday. If Message has a value, it is displayed after the original screen is restored in DOS, or in a message box under Windows. Generally, Message is used only to report fatal errors. The Command may be used to chain to other programs. Under DOS, the command is chained using COMMAND.COM /C to support batch files and full path specs. This command is omitted on the windows version to allow you to chain to a Windows program. If you are running the Windows version and want to chain to a DOS program, you will have to prefix your DOS command line with COMMAND.COM /C. In general, you can chain to any batch file, .COM file or .EXE file, and can pass up to 10 parameters (or 110 bytes whichever is longer) to that file. The JORF Manual (Shareware Disk Version) 172 Jorf:File Function Jorf:File ( Name Level ) Purpose Declares a project file, gets the name of existing project file. Returns Previous project file name. Notes Project files hold indexes and data, classes and methods. All of a JORF language application can run out of a single project file. However, it is advantageous to split various types of information into various files. Jorf:File declares a new file to be used by the interpreter. The new file is tied to the stack using Level, which must be the value of Here from the calling method. If the name and level are absent, this function just returns the current file. If they are present, the new file is used by the interpreter. Methods are searched in the current file, and then in the base project METHODS.JRF. The system also allocates a project called SWAPFILE.JRF for memory swapping. Indexed data is searched only in the current file. I created this use of files without precedent or experience. It much looser than any file definition I have ever seen in a computer system. However, it works, and it has some redeeming features. For one, the files are established in relative positions, and may be freely moved or renamed without compromising the data in those files. A file may even be shipped to another system, and used without any further set up. This works because the interpreter insures that the data and indexes in a given project file are always synchronized. The other redeeming feature is the simplicity of the scheme. You don't really open the file, allocate it, expand it or close it. This command basically says "Use this file for a while" and the interpreter does. Also Note When creating a program in the debugger, the interpreter automatically does a Jorf:File for the file you are working on. For instance, when you load the Haiku.J source file, the interpreter executes Jorf:File("Haiku.Jrf",Here) before it runs the program. Chapter Five - JORF Functions 173 However, if you translate your program to the C language, and compile it, the interpreter is no longer available, and you must open the file yourself. The best explanation of how this system works comes from running the interpreter with the Memory Info=Yes flag set in the JORF.INI file. This creates a display of memory usage and current file information. If you run the tutorial, you can watch the system switch to the tutorial file, and the help file, when you enter those menus. The following command will flush if there is less than 50 K (or 51,200) bytes available in the free memory pool: Jorf:Flush( 50 ) Example See Jorf:Write. The JORF Manual (Shareware Disk Version) 174 Jorf:Flush Function Jorf:Flush ( Size ) Purpose Flushes memory to disk. Returns None. Notes If Size is present and not zero, checks to see if that much memory (in kilobytes) is available. If so, then does nothing. If not, then flushes memory to obtain space. Always flushes if Size is zero or absent. This command may be used to insure that a particular procedure, like obtaining entry from a data input screen, can be completed without unnecessary delays due to memory flushes. Items that are flushed generally fall into two categories; items that are needed again, and items that are not. Those which are needed again will be read from disk resulting in spectacular performance degradation. Those which are not will stay on disk where they belong. JORF uses this command internally whenever it runs out of memory. It is supplied here as a Function because some Methods may see improved performance if memory is checked and flushed before or after they are invoked. Chapter Five - JORF Functions 175 Jorf:Info Function Jorf:Info ( InfoValue ) Purpose Get information about the JORF environment. Returns None. Notes The variable InfoValue should be a string with one of the following values. The return value is as noted. This function is a catchall to pass some quirky internal values and DOS environment values to JORF language programs. Value Returned Value NumFiles Number of JORF files open MemFree Current free memory DosVer MS-DOS Version DiskFree Amount of free disk space DiskCap Capacity of current disk Windows TRUE for Windows version Graphics TRUE if in graphics mode Env:Value If Value is in DOS environment, returns environment value. Otherwise returns Null. If you use the letters "ENV" followed by a colon, and then the name of a DOS Environment variable, the value of that variable is returned. For instance, to get the current DOS path, use the command Jorf:Info ( "Env:PATH" ). Upper and lower case does not matter, even for the environment variable name. More values are intended in the future. If you need a DOS environment value for your application, please give a call. If it does not require too much additional code (The size of the EXE file in the DOS version is really maxed out) I will try to add it for you. Example See Jorf:System, sample program DOS.J which checks "Windows" to see if you are running the Windows version. The JORF Manual (Shareware Disk Version) 176 Jorf:Ini Function Jorf:Ini Purpose Re-read JORF.INI file. Returns None. Notes A large number of system parameters are set in the JORF.INI and JORFWIN.INI files. This function allows you to change these values inside a JORF program. To set new values, write to the file using the normal file read and file write commands. Then call Jorf:Ini() to reset the initialization parameters. If you change video mode or screen colors, the windows that have already been displayed will not be changed. To effect a change, you will have to remove all windows and redisplay them from scratch. There is currently no automatic system for re-displaying the windows to reset colors. Example This predecessor to the EDITINI.J sample file could actually change colors on-the-fly. It is dangerous to change other parameters, like MultiUser. Colorset:Start New (IniFile) IniFile = Str:At(Mem:Ptr->Args,1,Str:In(Mem:Ptr->Args,'.')) IniFile = IniFile+'INI' Event:Add() While (Ok) Win:Add ("Set Colors") MLine:"&Bright Blue " Action:"ColorSet:Set('Blue')" MLine:"&Windows White " Action:"ColorSet:Set('White')" MLine:"&JORF Default " Action:"ColorSet:Set('Default')" MLine:"&Grey Green " Action:"ColorSet:Set('Gray')" MLine:"&Emerald Green " Action:"ColorSet:Set('Green')" MLine:"&Monochrome " Action:"ColorSet:Set('Mono')" MLine:"&Rev Monochrome " Action:"ColorSet:Set('RevMono')" MLine:"E&xit " Action:"Return('Esc_Key')" Win:Del If (Kbd:Got=='Esc_Key' Or Kbd:Got=='X_Key') Break Return Ok ColorSet:Set(Color) New (Line,Indent) If (Str:In(IniFile,"WIN")==0) | Setting DOS colors Chapter Five - JORF Functions 177 Switch (Color) Case 'Blue' Colorset:Write +Mono/Color=Mono +Line Style=single +Border=Bright Cyan/Blue +Title=Bright White/Cyan +Shadow=White/Black +Normal=Bright Cyan/Blue +Low=Bright White/Blue +Medium=Light Blue/Blue +High=Bright White/Cyan +Bold=Bright Cyan/Cyan +Message=Yellow/Blue Case 'White' Colorset:Write +Mono/Color=Mono +Line Style=Thick +Border Color=Bright White/White +Title Color=Bright White/White +Shadow Color=Black/Gray +Message Color=Gray/White +Normal Color=Bright White/White +Low Color=Gray/White +Medium Color=Bright White/White +High Color=White/Gray +Bold Color=Bright White/Gray Case 'Default' Colorset:Write +Mono/Color=Mono +Line Style=single +Border=Bright White/White +Title=Light Blue/White +Shadow=Light Magenta/Blue +Normal=Bright White/White +Low=Yellow/White +Medium=Light Blue/White +High=Yellow/Blue +Bold=Bright White/Blue +Message=Yellow/White Case 'Gray' Colorset:Write +Mono/Color=Mono +Line Style=Double +Border Color=Bright Cyan/Gray +Title Color=Bright White/Gray +Shadow Color=Cyan/Black +Message Color=Bright Yellow/Gray +Normal Color=Bright White/Gray +Low Color=Bright Yellow/Gray +Medium Color=Bright Cyan/Gray +High Color=Bright Yellow/Cyan The JORF Manual (Shareware Disk Version) 178 +Bold Color=Bright White/Cyan Case 'Green' Colorset:Write +Mono/Color=Mono +Line Style=Double +Border Color=Bright Green/Cyan +Title Color=Bright White/Green +Shadow Color=Cyan/Black +Message Color=Bright Yellow/Cyan +Normal Color=Bright White/Cyan +Low Color=Bright Yellow/Cyan +Medium Color=Bright Cyan/Cyan +High Color=Bright Yellow/Gray +Bold Color=Bright White/Gray Case 'Mono' Colorset:Write +Mono/Color=Mono +Line Style=Double +Border Color=Bright White/Black +Title Color=Bright White/Black +Shadow Color=White/Black +Message Color=Bright White/Black +Normal Color=White/Black +Low Color=Bright White/Black +Medium Color=White/Black +High Color=Black/White +Bold Color=Black/White Case 'RevMono' Colorset:Write +Mono/Color=Mono +Line Style=Double +Border Color=Black/White +Title Color=Black/Bright White +Shadow Color=White/Black +Message Color=Black/Bright White +Normal Color=Black/White +Low Color=Black/Bright White +Medium Color=Black/White +High Color=White/Black +Bold Color=Bright White/Black Return (Ok) ColorSet:Write(NewText) New (NewFile,Found) Win:Add Rewriting INI file NewFile = Str:At(IniFile,1,Str:In(IniFile,'.')) + "NEW" File:Del(NewFile) File:Open(NewFile,Here) File:Open(IniFile,Here) While (File:Ok(IniFile)) Line = File:Read(IniFile) Chapter Five - JORF Functions 179 If (Str:In (Line,"Window") And Str:In (Line,"Text")) Found=True File:Write(NewFile,"Window=Text") Indent = Str:Ind(NewText) While (Str:Ind(NewText)>=Indent) File:Write(NewFile,Str:At(NewText,Indent)) NewText=Text:Next(NewText) While (File:Ok(IniFile)) Line=File:Read(IniFile) If (Str:At(Line,1,1)!='+') Break File:Write(NewFile,Line) If (Found==Null) Msg:Add Could not find Window=Text line in the INI file. Else File:Backup(IniFile) File:Rename(NewFile,IniFile) Jorf:Ini() | <--Here it is way at the bottom Return (Null) The JORF Manual (Shareware Disk Version) 180 Jorf:Lock Function Jorf:Lock( Structure ) Purpose Locks a record, reports locked status. Returns Null if record is already locked, OK if a new lock was placed. See Also Jorf:Unlock, Jorf:Write. Notes The Structure is a JORF language structure that is used to hold fields to be stored to the disk. This function works with Jorf:Unlock and Jorf:Write to enable you to do record level locking. Record locking is used to prevent two people from changing the same record at the same time. If you do not have "Multiuser=Yes" set in your JORF.INI or JORFWIN.INI file then this function has no effect. To prevent two people from editing a record, the record must be locked whenever it is being changed. In JORF, the process of locking and the process of checking whether a lock is in place are both done using the Jorf:Lock function. Before editing a record (structure), you should call this command. If the Jorf:Lock result code is OK, (OK, Numeric 1, or True are the same in the JORF language) then you have locked the record properly and the edit can continue. If the result code is NULL (or 0) then someone else has the record locked and you should not edit it. In multiuser systems, structures are re-read from disk when locked to insure they contain information that may have been written by another operator just prior to locking by the current operator. When the editing is complete you have the choice of aborting the change, or accepting the change and writing to disk. If you wish to abort, use the Jorf:unlock function. This function unlocks the record and re-reads it from file, restoring the original values. To keep the changed information, use Jorf:Write, which will write the changed data and automatically unlock the record. If you fail to unlock or write the record after locking, it will remain locked until the file is rebuilt using Jorf:Rebuild. This is very bad to have Chapter Five - JORF Functions 181 records locked, and you should never allow a function to exit without unlocking or writing the current record. For File Pros: The JORF locking system does more than just set a software lock. It actually locks only the header of the file long enough to write a physical marker in the stored record, the record is rewritten and header is unlocked. That is why a locked record remains locked, even though you exit JORF and even reboot your computer. The Jorf:Rebuild function runs under an exclusive file lock and automatically clears releases the physical lock bit for all records. Locked records are not owned, so one user (or supervisor function) can unlock a record locked by another user. For File Novices: A common problem happens in programs that use multiple file locks. If the program locks two records in one place, and two records in another place (say a contact record and an order record) you can get a situation called deadlock. This happens when one operator locks the first, another operator locks the second, and the function the first operator is running does not release the first until the second is available. Like the name implies, Deadlock is to be avoided at all costs. Three ways to avoid deadlock are: A sure way: Avoid ever having two file locks. A creative programmer will realize that while we are editing the Order, we are not editing the Contact, and set locks accordingly. If you never lock two records at once, you cannot have deadlock. A good way: Always lock files in the same order, and unlock them in reverse order of locking. Always lock Contact, then Order, and release Order then Contact. This will always work, but requires discipline and planning, especially when you consider that reports and batch processes may also be locking and releasing the records. A bad way: If the second record is locked, release the first while waiting for the second to be released. This is a kludge that requires even more discipline and planning. One mistake and you will still have deadlock. There are other techniques to avoid deadlock. The worst way is to ignore it. You might think "This data base has 10,000 records so there is only a 1 in 10,000 The JORF Manual (Shareware Disk Version) 182 chance that two operators will be in the same record". In real life it is common to see an operator who is modifying a record, has a question and goes to consult another operator who attempts to modify the same record. Or the case where two salespeople are both working on a very important customer's order. Taking care with your locking is necessary to insure that your application runs smoothly in all these circumstances. Chapter Five - JORF Functions 183 Jorf:Move Function Jorf:Move (Source, Dest, Class ) Purpose Move elements of a structure. Returns None. Notes If you just want to duplicate a structure, use Jorf:Dupe. Sometimes, however, you want to transfer only like-named elements of a structure. For that reason alone this function exists. The use of this function is pretty obscure. Lets say you have a structure like "C" which is a member of the "Control" class, and it shares elements with a structure like "P" which is a member of the "Project" class. You can quickly transfer "Project" elements with the following command: Jorf:Move ( C, P, "Project") Note the class name is passed as a string, and must be quoted. An even more obscure use of this command is to set specific elements to blank. You can do this by using Null as the source. You can set all elements without specifying a class, or only the elements of a class. Jorf:Move (Null, P) | Blank out Project P Jorf:Move (Null, C, "Project") | Blank out "Project" elements of C The JORF Manual (Shareware Disk Version) 184 Jorf:Pack Function Jorf:Pack Purpose Packs a JORF file. Returns None. See Also Jorf:Rebuild. Notes Converts the current JORF file to a special ASCII file format. This format retains all data, but omits any indexes. It also contains offsets to recursive structures and sparse structures such as large arrays. Packed files have the extension JPK. Because the packed format does not contain indexes, it is usually half the size of the .JRF file. This file can be used to rebuild a .JRF file. The file must be rebuilt with the appropriate class definitions, so that indexes are added properly. Chapter Five - JORF Functions 185 Jorf:Printer Function Jorf:Printer Purpose Displays a preprogrammed printer selection box. Returns None. See Also Arr:Printers, File:Print Notes This command displays a standard pre-programmed printer selection box to save you the time of creating one. It is really a JORF language routine, translated and compiled into the JORF interpreter. The example below shows the actual code for this routine. Example Jorf:Printer New (PrintList,PrintChoice,Dest) Event:Add() PrintList = Arr:Printers() Win:Add("Select Printer") Group:"&Printers", Row:1 Col:1 Len:6 Wid:22 Array:"" Field:"PrintList" Choice:"PrintChoice" Button:" &Go " Row:1 Col:32 Action:"Dest=PrintList[PrintChoice]" Button:" &Cancel " Row:4 Col:32 Action:"Return ('Esc_Key')" If (Dest='Esc_Key' Or Kbd:Got='Esc_Key') Dest=Null Return(Dest) The JORF Manual (Shareware Disk Version) 186 Jorf:Rebuild Function Jorf:Rebuild Purpose Packs and rebuilds a JORF file. Returns None. See Also Jorf:Pack. Notes Rebuilds a .JRF file by copying data to an ASCII format, erasing the original, and reading the ASCII data back in. Indexes are not copied, and are re- created after the data is read. To rebuild a file, you must not be using any methods or data in that file. The rebuild will clear live pointers (which are changing position) so you will have to redraw your screens after rebuilding.. You can rebuild from the command line using the -R option. You must first specify the file that contains the class definitions, and then -R and then the file(s) you want rebuilt. C>JORF Contact -R Maillist.JCM The command above rebuilds the file Maillist.JCM according to the class definition found in Contact.J. Chapter Five - JORF Functions 187 Jorf:Sound Function Jorf:Sound ( Frequency, Duration ) Purpose Make beautiful music. Returns None. Notes The built in sound capability in the IBM PC style computer is very primitive. You cannot control volume and the PC uses a square wave that sounds very mechanical. This command makes a sound at the specified Frequency for at least the specified Duration (in 18ths of a second). The sound ends when the duration is ended. Using a frequency below 20 may be inaudible or may damage some computer speakers. The JORF Manual (Shareware Disk Version) 188 Example I had a lot of fun writing MUSIC.J. Music:Start New(Response,Row,Col,Forg,Back,Tone,Time) Response=Msg:Add("Beautiful Music") This 42 line program generates random music. Just in case you do not like random music, I have made the program display a tapestry of color proclaiming Beautiful Music to convince you. It is a demonstration for these functions: Num:Rand(Lo,Hi) -Generates random numbers Jorf:Sound(Tone,Duration) -Plays a musical tone Win:Attr("Foreground/Background") -Changes screen colors You are encouraged to change this program around to change the music and the colors. For instance make the music higher or lower, faster or slower, and make the colors follow the rainbow instead of being random. (We wasted 18 lines just on this message . . . only 20 lines to go!) You could spend hours here, making Beautiful Music! If (Response==Ok) Win:Add ("Beautiful Music", 2, 3, 22, 75, Here) Win:Msg ("Press any key for relief . . .") While (Kbd:Hit()==0) | Do until they give up ++Row | Next row If (Row > Win:Ptr->Len) | If too low Row=1 | back to row 1 For (Col = 0 thru 4) | Display B Music 5 times Forg=Num:Rand(0,15) Back=Num:Rand(0,15) Move:To(Row,(Col*15+1)) Win:Attr(Forg+"/"+Back) Str:Put("Beautiful Music") Time=Num:Btw(Time*Num:Rand(-4,4),1,8) Tone=Tone+((Tone/12)*Num:Rand(-2,2)) If (Tone<60 Or Tone > 1400) Tone=440 Jorf:Sound(Tone,Time*40) Return (Ok) Chapter Five - JORF Functions 189 Jorf:System Function Jorf:System ( Command, Flags, Message ) Purpose Execute DOS shell or DOS command. Returns Ok if executed, Null if not. See Also Jorf:Exit. Notes This command allows you to execute any DOS command or run other programs in a DOS shell. If Command is not used or is Null then the operator will be transferred to an operating system shell and must type EXIT to return to JORF. The Flags is a string of letters with any of these values: "C" DOS Only Clear screen when shelling out. "P" DOS/Windows Pause message before returning "W" Windows Only Spawn a Windows executable and return immediately. More flags are anticipated. The Message will be printed on the screen before the DOS command is executed. It should only be used when the "C" flag is indicated to clear the screen. The message is assumed to be something useful like 'Type "Exit" to RETURN'. The Message is ignored if you use the "W" flag. DOS Version You will only have about 200K memory for your DOS command. This is too small to run most application programs, but is just fine to run DOS utility programs like Format, Copy and Undelete. Windows Version There are two variations to this command. If you want to launch a Windows program, include the "W" flag. The program will launch the program and return control back to the originating program. If you want to run a DOS command, do not use the "W" flag and the The JORF Manual (Shareware Disk Version) 190 DOS command will be run as in the DOS version. When running without the "W" flag, a small batch file called JSYSTEM.BAT will be created (JSYS9999.BAT on multiuser systems where 9999 is a random number). This file is responsible for handling the "P" flag and Message parameter. JORF will shell into your command using the DOS COMMAND.COM interpreter. When running without the "W" flag the size of the window is controlled by a PIF file. You can change the defaults by creating a PIF file called COMMAND.PIF that controls the COMMAND.COM program. If you do this and turn "Full Screen" off, then your system commands will be windowed. Under Windows 3.1 you can also set the Font and size of the window. To obtain as much memory as possible, the system automatically calls Jorf:Flush before executing this call. Also, all files are closed before executing the shell. Example This program came from a user (with a bug). Now that the bug is fixed the program is kinda fun. DOS.J. Dos:Start Win:Add("Jo's DOS Function Utility", 0, 0, 20, 44) This program allows the user to & select special DOS commands. Place your mouse over the desired & selection and click the Left Mouse & Button or you may use the up and down & arrow keys to select the desired command. {Group:"DOS Commands" Row:9 Col:5 Len:10 Wid:30} {Prompt:"&Memory Stats " Row:11 Col:7 Wid:25 Action:"Dos:Cmd('Mem')"} Chapter Five - JORF Functions 191 {Prompt:"&Command Shell " Row:12 Col:7 Wid:25 Action:"Dos:Cmd('Shell')"} {Prompt:"Directory by &Date" Row:13 Col:7 Wid:25 Action:"Dos:Cmd('DirDate')"} {Prompt:"Directory by &Size" Row:14 Col:7 Wid:25 Action:"Dos:Cmd('DirSize')"} {Prompt:"&Type in a Command" Row:15 Col:7 Wid:25 Action:"Dos:Cmd('TypeIt')"} {Prompt:"&Windows Program " Row:16 Col:7 Wid:25 Action:"Dos:Cmd('Windows')"} {Prompt:"E&xit " Row:18 Col:7 Wid:25 Action:"Return(Null)"} Return (Ok) Dos:Cmd(Action) New (Command, Flags, Message) Switch (Action) Case 'Mem' Command = "Mem /c | More" Flags = "CP" Case 'Shell' Command = Null Flags = "C" Message = "Type 'EXIT' to return to JORF" Case 'DirDate' Command = "Dir /o-d | More" Flags = "CP" Message = "Sorting . . ." Case 'DirSize' Command = "Dir /o-s | More" Flags = "CP" Message = "Sorting . . ." Case 'TypeIt' Win:Add Input:"Command to execute:", Field:"Command" If (Kbd:Got=='Esc_Key') Return Flags = "C" Case 'Windows' If (Jorf:Info("Windows")==False) Msg:Add This option only works in the & Windows version of the JORF interpreter. Return Win:Add Input:"Windows program:", Field:"Command" If (Kbd:Got=='Esc_Key') Return Flags = "W" Else Msg:Add Illegal DOS Command "{Action}". Return (Ok) Jorf:System (Command, Flags, Message) Return (Ok) The JORF Manual (Shareware Disk Version) 192 Jorf:Unlock Function Jorf:Unlock( Structure ) Purpose Unlocks a record, reports locked status. Returns Null if record is not locked, OK if properly unlocked.. See Also Jorf:Lock, Jorf:Write. Notes The Structure is a JORF language structure that is used to hold fields to be stored to the disk. This function works with Jorf:Lock and Jorf:Write to enable you to do record level locking. This function is used primarily to unlock and restore the value because the operator decided not to change the record. If you want to store changes, you should use Jorf:Write to unlock the record. When you use Jorf:Unlock, the structure is automatically re-read from disk and any changes will be lost. If you do not have "Multiuser=Yes" set in your JORF.INI or JORFWIN.INI file then this function has no effect. Chapter Five - JORF Functions 193 Jorf:Write Function Jorf:Write ( Item ) Purpose Write an item to current Data file. Returns None. See Also Jorf:Del. Notes Writes Item to the current project file. This function permanizes a structure so that it can be recalled later. It is used: 1. To write a structure as a record, with index references in the current project file. 2. When you want to insure a text or array value is in the current project file. 3. When you have an empty new variable that may soon become an array or a text pointer that you want written in the current project file. This command is intimately tied up with the JORF system of "Object Persistence". Normally we think of all JORF variables as memory variables. Unlike most languages, however, the JORF Language features automatic movement of these variables to disk. When a structure is written to a disk file, it goes into the current project file currently declared using Jorf:File. When written, all elements of the structure are rewritten into the same project file. This is important: You cannot write any record that references information in another file. If you directly reference another structure, that other structure is completely rewritten into the current file. The only way to create a "Relational" Link between separate files is to store a look up value for the secondary file. Rewriting large Arrays and blocks of text are especially slow. If you create a large text in memory, and the system runs out and flushes the text to disk temporarily, it will be flushed to the SWAPFILE.JRF project file. If after finishing your large text you attach it to a structure that is to be written to another file, the entire text will be read from one file and duplicated in the second file. Programmers will note how wasteful and slow this can become. The JORF Manual (Shareware Disk Version) 194 Instead, create the first line of text and use Jorf:Write to write it to the eventual destination project. Then add the rest of the lines. If the interpreter needs to flush memory, the partial text will be written to the correct location so that time and disk accesses are saved later. This function works with Jorf:Lock to provide record level locking. If a locked record is written using Jorf:Write then the lock is automatically released. Example I've always enjoyed the Haiku generator. Chapter Five - JORF Functions 195 Class:Haiku Index:Key | A "Key" to store this structure Text | Current Haiku Text Arts | Sentence articles Adjs | Adjectives Nouns | Nouns Verbs | Verbs Preps | Preps Haiku:Start New (Haiku:Haiku) Jorf:File ("Haiku", Here) Haiku=Haiku:GetStructure() Haiku:Thinkup(Haiku) Win:Add("Haiku Generator", 4, 15, 10, 50, Here) Menu:"&File" Menu:"E&xit" Action:"Jorf:Exit" Menu:"&Print" Action:"Haiku:Print(Haiku)" Group:"" Row:2 Col:5 Len:3 Wid:40 | Group box border Text:"" Field:"Haiku->Text" | Text to show Before:"Null" | Never any input here Button:"&Generate" Row:8, Col:5 Wid:20 Action:"Haiku:Thinkup(Haiku)" Button:"E&xit" Row:8, Col:27 Wid:20 Action:"Jorf:Exit()" Return (Ok) Haiku:Array (Text) | This routine loads words into an array. Double words must be quoted. | The Array is written to the current file (HAIKU.JRF). New (WordCount, Arr, ArrCount, Spaces) Spaces = Str:Ind(Text) | Indent level While (Text And Spaces <= Str:Ind(Text)) For (WordCount = 1 thru Word:Len (Text)) | For each word ++ArrCount | Add word to Arr[ArrCount]=Word:At (Text, WordCount) | word array Text = Text:Next (Text) | Next line Jorf:Write (Arr) | Write to current file Return (Arr) Haiku:Generate (Haiku, Text) New (Spaces, CurWord, Pos) New (NewWord, NewLine, NewText) Spaces = Str:Ind (Text) While (Text And Spaces <= Str:Ind(Text)) | Step backwards - so we can switch "A" to "AN" when necessary For (Pos = Word:Len (Text) thru 1 Step -1) CurWord = Word:At (Text, Pos) Switch (CurWord) Case 'Art' The JORF Manual (Shareware Disk Version) 196 NewWord = Haiku:GetWord (Haiku->Arts) If NewWord = "a" If (Str:Aft (NewLine,"aeiou") < 2) NewWord = "an" Case 'Noun' NewWord = Haiku:GetWord (Haiku->Nouns) Case 'Adj' NewWord = Haiku:GetWord (Haiku->Adjs) Case 'Verb' NewWord = Haiku:GetWord (Haiku->Verbs) Case 'Prep' NewWord = Haiku:GetWord (Haiku->Preps) Else NewWord = CurWord If (Pos = 1) NewWord = To:Caps (NewWord) NewLine = NewWord + NewLine NewText = Text:Add (NewLine, NewText) NewLine = Null Text = Text:Next (Text) Haiku->Text = NewText Return (Ok) Haiku:GetStructure | Get Haiku structure from file. If not found in file, generate | it from the word lists. New (Haiku:Haiku) Haiku = Struct:Find("Haiku","Key",Null) If (Haiku == Null) Haiku->Arts = Haiku:Array() a the Haiku->Adjs = Haiku:Array() autumn hidden bitter misty silent empty dry dark sighing delicate quiet white cool frigid winter dappled twilight afternoon crimson wispy azure blue billowing broken cold damp falling frosty tawny long late lingering little morning leafy billowing still small sparkling cloudy wandering withered wild black young Haiku->Nouns = Haiku:Array() waterfall mist breeze moon rain wind sea morning snow glitter forest Josephine cloud meadow sun glade bird brook butterfly tove dew savannah meadow flower firefly feather grass haze mountain night goat shade snowflake silence lily sky shape surf thunder violet water wildflower wave Haiku->Verbs = Haiku:Array() drifts "has stopped" blusters blows Chapter Five - JORF Functions 197 races "did gimble" stretches flutters has risen "is drifting" "is trickling" murmers "is floating" "is wafting" Haiku->Preps = Haiku:Array() on in beneath over near of Haiku->Key = "Key" Jorf:Write (Haiku) Return (Haiku) Haiku:GetWord (Arr) New (Word, Off) Off = Num:Rand (1, Word:Len (Arr)) Word = Arr[Off] Return Word + " " Haiku:Print(Haiku) New (Dest) Dest=Jorf:Printer() If (Dest!=Null) File:Save("JREPORT.LST",Haiku->Text) File:Append("JREPORT.LST") File:Print("JREPORT.LST",Dest,TRUE) Return (Ok) Haiku:Thinkup(Haiku) Switch Num:Rand (1, 4) Case 1 Haiku:Generate (Haiku) Art Adj Noun . . . Art noun verb prep art noun Adj Adj Noun Case 2 Haiku:Generate (Haiku) Noun Prep Art Noun Art Adj Noun Prep Art Noun Adj Noun Case 3 Haiku:Generate (Haiku) Art Adj Noun Art Adj Noun Art Noun Verb Case 4 Haiku:Generate (Haiku) Art Adj Noun Verb Art Adj Noun Prep Art Adj Noun Win:Dsp Return(Ok) The JORF Manual (Shareware Disk Version) 198 Kbd:Bye Function Kbd:Bye Purpose Clear keyboard stream. Returns None. See Also Kbd:Get. Notes Kbd:Bye does not read or process the keys, it just gets rid of them. Chapter Five - JORF Functions 199 Kbd:Get Function Kbd:Get ( CursorSize ) Purpose Get a Keystroke from the Keyboard. Returns Keystroke value. See Also Kbd:Hit, Kbd:Got, Kbd:Put, Line:Inp. Notes Waits until the operator hits a key and returns the value of that character. If CursorSize is "None", no cursor is displayed. If it is "Little", then the cursor will be a blinking line, and if it is "Big", the cursor will be a blinking block. Only the first letter is significant. If it is absent or null, "Little" is assumed. The return value is always a string indicating the key that was hit. This is a departure from most language that returns an integer value. The key values are outlined in Appendix C. The Event System processes keystrokes using Event:Do Value "Key". This processing may change the value of the key, display a message, or move the cursor location. It is especially important during field input and text input to remember that the cursor location may change during a Key:Get. Example WhatKey:Start | Sample for: Key:Get, Event:Add New Key Win:Add ("What Key?", 5, 15, 10, 50) Win:Msg ("Press Alt-X to Quit") While (Kbd:Got!="Alt_X_Key") Str:Put ("Press a Key: ") Key = Kbd:Get ("Big") Str:PutLine ('That was the "' + Key + '".') Jorf:Exit The JORF Manual (Shareware Disk Version) 200 Kbd:Got Function Kbd:Got Purpose Find out what the last Keystroke was. Returns Keystroke value. See Also Kbd:Hit, Kbd:Get, Line:Inp. Notes Returns the value of the last keystroke. Always returns the key value, even if the event system may have caused Kbd:Get to return a different key value. The return value is always a string indicating the key that was hit. The key values are outlined in Appendix C. Chapter Five - JORF Functions 201 Kbd:Hit Function Kbd:Hit Purpose Check to see if a key has been hit. Returns True if a key has been hit. Otherwise False. See Also Kbd:Get. Notes Kbd:Hit does not read or process the keystroke in any way. To find out what key was hit, use Kbd:Get. The JORF Manual (Shareware Disk Version) 202 Kbd:Put Function Kbd:Put ( Value ) Purpose Stuff the keyboard buffer with keys. Returns None. See Also Kbd:Get. Notes This function allows you to stuff any keys, including mouse keys, into the input buffer. There are three basic formats you can use: 1. An individual keystroke command. 2. A string of characters to stuff. 3. Some text where each line is either 1 or 2. It is common to mix these two formats. For instance, to stuff the keyboard to fill three data entry fields, you might use the following six commands: Kbd:Put ("This goes into Field 1") Kbd:Put ("Tab_Key") Kbd:Put ("This goes into Field 2") Kbd:Put ("Tab_Key") Kbd:Put ("This goes into Field 3") Kbd:Put ("Enter_Key") To stuff commands in "Text" format, you can simply indent them: Kbd:Put() This goes into Field 1 Tab_Key This goes into Field 2 Tab_Key This goes into Field 3 Enter_Key Handy note: On a data entry screen, the Home key goes to the first, and the End key goes to the last button on the screen. Use this fact to establish your referencec to variaous buttons. After keys are stuffed the JORF language cannot tell them from keys that are input. The keyboard handling system as a dynamically reallocating buffer, that is limited only by the size of your near memory. You can generally stuff more than 1000 keystrokes without running out of memory. Chapter Five - JORF Functions 203 Key:Add Function Key:Add ( RuleStructure ) Purpose Add a String Key to the data base. Returns None. See Also Rule:Add. Notes RuleStructure must be a compound structure with the elements Type, Obj, Str, Ptr, Fnd (found), and KLen (Key Length). The last two elements are used by Key "Find" to get next key in a series. The elements Att and Val used by Rule:Find are replaced here by Str. Key:Add adds a new string key valued Obj and Str, with the associated data in Ptr. Probability cannot be added as with the Rule:Add function. The key may be found again by specifying the correct Obj, and by doing a partial or whole key search on the Str value. The JORF Manual (Shareware Disk Version) 204 Key:Del Function Key:Del ( RuleStructure ) Purpose Deletes an existing string key. Returns None. RuleStructure->Fnd will be True if key was found and deleted. See Also Key:Find. Notes Deletes an existing string key. This command may be called with a partial key value, in which case it will delete the first entry by that value. After an entry is deleted, you are still able to go the "next" entry. Example See Key:Add. Chapter Five - JORF Functions 205 Key:Find Function Key:Find ( RuleStructure ) Purpose Find a key. Returns None. See Also Rule:Find, Key:Next. Notes In this function, parameters may be empty, in which case the first matching index entry will be returned. Parameters must be empty from left to right, that is, if Str has a value then Obj also must have a value. If a "hole" is left, then nothing will ever be found. When a key is found, the structure will be filled with the values of that key and Fnd will be set to True. If Key:Next is called with these values set, then the next key value is returned. This process may be continued until the value of the current key does not match the value of the original partial key. This length is put in KLen after every successful search and may be modified. Although this process appears quirky, in practice it is easy and intuitive. Generally, string keys have a "type" in Obj. Commonly, the first key of that type is searched, and then all subsequent keys displayed since they have the same type. When the type changes in the index, the list has been completed. The JORF Manual (Shareware Disk Version) 206 Key:Next Function Key:Next ( RuleStructure ) Purpose Find next key in sequence. Returns None. See Also Key:Find. Notes If RuleStructure->KLen is zero, then this command works just like KeyFind. If it is not zero, then the next key in sequence is returned. When a key is found, the structure will be filled with the values of that key and Fnd will be set to True. This process may be continued until the value of the current key does not match the length specified. Values for Klen are: 0 Rules with the same Type match 1 Rules with the same Type+Obj match 2 Rules with the same Type+Obj+(Partial)Str match 3 Rules with the same Type+Obj+Str match Chapter Five - JORF Functions 207 Key:Prev Function Key:Prev ( RuleStructure ) Purpose Find previous index value. Returns None. See Also Key:Find, Key:Next. Notes This function is the opposite of Key:Next. The JORF Manual (Shareware Disk Version) 208 Line:Del Function Line:Del ( Count ) Purpose Delete a Count lines of text displayed in an editing window. Returns None. See Also Line:Inp. Notes Deletes Count lines of text on the input screen and handles appropriate scrolling functions. The text must have been displayed by a legitimate text input routine. Placing text on the window "by hand" does not make it an input structure appropriate for handling with this function. Lines will be inserted if Count is negative. Nothing will happen if it is zero. If the cursor is in column 1, then the line will be appended on the previous line. The Join ability makes it symmetrical with Line:Ins which can Split text lines. Chapter Five - JORF Functions 209 Line:Inp Function Line:Inp ( Field, Row, Column, Length, Width ) Purpose Input a data entry field or multiple line text. Returns None.. See Also Line:Out, Text:Add. Notes This command may now be functionally obsolete, replaced by the powerful window management Input command. Before the Window Manager existed, this was the only input command available,. For the moment, it does no harm to have an extra function that allows you to input a single item on a data entry screen. To Highlight the field before entry, use Line:Out. The JORF Manual (Shareware Disk Version) 210 Line:Ins Function Line:Ins ( Count ) Purpose Inserts Count lines in current edit window. Returns None. See Also Line:Inp, Line:Del. Notes Inserts Count lines at the current cursor location and handles appropriate scrolling functions. Lines will be deleted if Count is negative. Nothing will happen if it is zero. Example How about the Ctrl-N method from the editor. EditKey:Ctrl_N_Key | Insert Line Win:Ptr->Prefix=Null | ^Q Prefix is now meaningless EditKey:Changed | You've ruined it, must show menu Line:Ins (1) | Insert one line EditKey:Message | And show current pos and status Chapter Five - JORF Functions 211 Line:Out Function Line:Out ( Field, Row, Column, Length, Width ) Purpose Output a data entry field or multiple line text. Returns None. See Also Line:Inp, Text:Add. Notes This command may now be functionally obsolete, replaced by the powerful window management Input command. For the moment, it does no harm to have an extra function that allows you to input a single item on a data entry screen. To highlight, call Win:Att to set the attribute, then this command to display line or field with that attribute. The JORF Manual (Shareware Disk Version) 212 Line:Rel Function Line:Rel Purpose Release input, forcing data to be re-read from the field. Returns None. See Also Win:Dsp. Notes When data entry is done, there is an internal buffer that temporarily holds the field value. If a keystroke function changes that value, this buffer must be released, so that the value is re-read from the original field. This mechanism saves you from worrying about data displayed on the screen when you change it underneath. Use of this function is rare. Usually, you use Win:Dsp to redisplay all fields on the screen when entry is complete. Chapter Five - JORF Functions 213 Mem:Ptr Function Mem:Ptr Purpose Set or check global values. Returns None. Notes Global variables are values that may be tested and changed by any method. They are a key feature of the BASIC and dBASE languages. However, I don't like them one bit, because you can never really depend on them holding their values as program flow passes in and out of other people's subsystems. The JORF Language has only one true global variable, Mem:Ptr. This is a structure of the Jorf class. Structures of this class are allowed to have any element, without any declaration. As you run your program, any time you need to save a value, set it using Mem:Ptr. Later, you can retrieve it the same way: Mem:Ptr->Test = "Hi Jo" | Set global value "Test" Str:PutLine (Mem:Ptr->Test) | Use global value "Test" You should avoid using too many global variables. Doing so is an indication that your program is structured poorly and you are making up for it by kludging around. Instead, create new class structures to pass multiple values around your methods. Example See Event:Add. The JORF Manual (Shareware Disk Version) 214 Method:Add Function Method:Add ( Text ) Purpose Write text including indexes used by the interpreter to call methods. Returns None. See Also Method:Del. Notes This function differs from Jorf:Add only in that it looks for a method name on the first line, and if found, adds the appropriate indexes so the method may be found again. Methods are also indexed by Class:Read and Class:Check. This command does something distressing if the method already exists. If you are editing an existing method, there is no problem. But if you have created a new copy of an existing method, Method:Write must resolve this so there is only one copy. What it does is to move your current copy to the location of the existing copy. Your editing changes stick, but your pointer Text will be deleted. Whenever you use Method:Write, be aware that you may lose your pointer. Chapter Five - JORF Functions 215 Method:Del Function Method:Del ( Text ) Purpose Delete text including indexes used for calling method. Returns None. See Also Jorf:Del. Notes This function differs from Jorf:Del only in that it looks for a method name on the first line, and if found, deletes any index references. Methods are indexed automatically by Class:Read and Method:Add. There is no harm in passing all text to this command, it gives no error if the indexes are not found. Example See Method:Move. The JORF Manual (Shareware Disk Version) 216 Msg:Add Function Msg:Add ( Title, Type, Text ) Purpose Show a Dialog Box. Returns True or False. See Also Win:Add. Notes Displays one of four preset dialog boxes. All boxes have a message in the top section, and one or two buttons on the bottom. The four box Types are: Ok The Default, one button says Ok. Yes A Yes/No box, default is Yes. No A Yes/No box, default is No. Cancel An Ok/Cancel box, default is Ok. Message boxes use the "Message" background if it is defined in the JORF.INI or JORFWIN.INI file (See Appendix D). Under Windows, the message system uses a special dialog box that limits access to other windows. To create a message that uses a normal box, use Win:Add. Under MS-Windows the message box frame changes according to whether there is a title. If there is a title, the "Dialog box" frame is used, if there is no title, the "Wire" frame is used. The reason is simple and stupid, it seems that Windows won't allow me to create a non-dialog box with a dialog box frame and a title. Example You can quickly try all the message boxes using the MSGBOXES.J sample program. Chapter Five - JORF Functions 217 Move:By Function Move:By ( Row, Column ) Purpose Move cursor in window. Returns None. See Also Move:To. Notes Works the same as Move:To Row Column except that movement is relative to the current position. It is common to see negative numbers used in this command to move back one row or column. A movement that exceeds window boundaries place the cursor as far as possible without going over the boundary. There is no way to move outside a window. The JORF Manual (Shareware Disk Version) 218 Move:To Function Move:To ( Row, Column ) Purpose Move cursor in window. Returns None. See Also Move:By. Notes Moves the present position to Row and Column coordinates in the current window. A position that exceeds window boundaries place the cursor next to the boundary. There is no way to position the cursor outside a window. Row may be zero, in which case the cursor will not be moved up or down. Row may also be negative, in which case the cursor will be that many lines from the Bottom of the window. The top row of a window is Row 1, and the bottom is WindowPacket->Length. Column may be zero, in which case the cursor will not be moved right or left. Column may also be negative, in which case the cursor will be that many characters from the left side of the window. The leftmost character is in column 1, and the rightmost is in column WindowPacket->Width. A movement that exceeds window boundaries places the cursor as far as possible without going over the boundary. There is no way to move outside the current window. Example See Jorf:Sound. Chapter Five - JORF Functions 219 New Function New ( Variable1, Variable2, Variable3 ) Purpose Creates new variables. Returns None. Notes Creates a new instance of an object. This command is the only way to allocate structures and new records on disk. New must be used at the beginning of a method, before any other commands. New variables are automatically deallocated unless: They are linked to a rule. They are linked to a structure, linked to a rule. They are linked to Mem:Ptr or Win:Ptr. They are Returned. You can declare more than one variable, by listing them one after another. Variables names may be prefixed by a class, separated with a colon. Variables may also omit the class, implying they belong to the Jorf class. Variables of the Jorf class will take on the class of another value that is assigned to them. The JORF Manual (Shareware Disk Version) 220 Example The Quick Demo in the tutorial writes this method: Demo:Start New (Rad, Chk, Inp1, Inp2) Win:Add ("A Real Screen", 4, 8, 14, 50, Here) Menu:"&Help" Menu:"&Indented Menu Items" Menu:"&Create Sub Menus" Menu:"&And Even Deeper" Menu:"&Sub Menus" Menu:"(Escape to Exit)" Menu:"&Jorf Help F1" Action:"Hotkey:F1_Key" Menu:"&Time and Date Alt-T" Action:"HotKey:Alt_t_Key" Radio:" Radio &1" Row:6 Col:8 Check:"Rad==True", Action:"Rad=True" Radio:" Radio &2" Check:"Rad==False", Action:"Rad=False" ChBox:" Check Box &A" Row:6, Col:26 Check:"Chk==True", Action:"Chk=True" ChBox:" Check Box &B" Check:"Chk==False", Action:"Chk=False" Input:"&Input 1 " Row:9, Col:8 Field:"Inp1" Input:"I&nput 2 " Field:"Inp2" Button:" &Done " Row:12, Col:24, Action:"Esc_Key" Return Chapter Five - JORF Functions 221 Null Function Null Purpose Returns "Nothing". Returns "Nothing". See Also True. Notes Returns a JORF Pointer to nothing. This is used like a 0 is used in decimal location. Sometimes you need indicate "nothing", but it has to be something to keep other items aligned. This is equivalent to closed quotes ("") or the number zero. The JORF Pointers for zero, "" and null are exactly the same. The JORF Manual (Shareware Disk Version) 222 Num:Abs Function Num:Abs ( Num ) Purpose Returns the absolute value of Num. Returns Num or -Num. See Also Num:Max, Num:Min. Notes The Absolute value is the same number, but always positive. So the absolute value of -5 is five, which is also the absolute value of 5. This function is used to insure that negative numbers are treated like their positive equivalent. This function maintains the internal type of the number. If the number is a floating point number, a floating point number is returned. If it is an integer, an integer is returned. If it is a string or text, then the string is converted to a number, and a floating point or integer value is returned. Chapter Five - JORF Functions 223 Num:Btw Function Num:Btw ( Num, A, B ) Purpose Returns Num between A and B. Returns Num, A or B. See Also Num:Max, Num:Min. Notes Num is between, then the return value is Num. If it is lower than A, then A is returned. If higher than B then B is returned. This function is used to qualify that a value is within a specific range. The JORF Manual (Shareware Disk Version) 224 Num:Exp Function Num:Exp ( Num ) Purpose Returns the exponential e to Num. Returns Exponential e to Num. See Also Num:Log. Notes Frankly I don't really understand what this is except that e is a complex number that shows up in some math algorithms. Mine is not to question why, but to give you the capability. Chapter Five - JORF Functions 225 Num:Log Function Num:Log ( Num ) Purpose Returns the natural logarithm of Num. Returns The natural logarithm of Num. See Also Num:Sqrt, Num:Pow. Notes The logarithm is another mathematical concept I don't fully understand, but it was what one of Babbage's great machines was to calculate so it must be important. Example To calculate loan payment quickly, logarithms saves doing an iterative analysis. See PAYMENT.J The JORF Manual (Shareware Disk Version) 226 Num:Max Function Num:Max ( A, B ) Purpose Returns the higher of A and B. Returns Either A or B. See Also Num:Btw, Num:Min. Notes Corresponds to a common C language macro MAX(A,B). Use this command to return the Highest of two values. There is an odd paradox that you commonly use these numbers to insure a minimum value. For instance, to produce a number no lower than 10, you call Num:Max Number, 10. Chapter Five - JORF Functions 227 Num:Min Function Num:Min ( A, B ) Purpose Returns the lower of A and B. Returns Either A or B. See Also Num:Btw, Num:Max. Notes Corresponds to a common C language macro MIN(A,B). Use this command to return the Highest of two values. There is an odd paradox that you commonly use these numbers to insure a maximum value. For instance, to produce a number no higher than 10, you call Num:Min (Number, 10). The JORF Manual (Shareware Disk Version) 228 Num:Pow Function Num:Pow ( Num, Pow ) Purpose Returns Num raised to the Pow power. Returns Power of Num. See Also Num:Sqrt. Notes Returns Num raised to the indicated power. The result is an integer only if it fits, and is a floating point if it is fractional or very large. Example See Num:Log Chapter Five - JORF Functions 229 Num:Rand Function Num:Rand ( Low, High ) Purpose Produces a Random Number. Returns A Random Number from Low through High. Notes Produces a pseudo random number between High and Low that are assumed to be integer values. The random number seed is the system clock and will be different for each run of JORF. The number may be Low or High or any integer value between. Example The MANTRA.J sample program uses random row and column for placing windows. Mantra:Start New (Counter) Msg:Add("Mantra") This next sample programs will display some windows & and get some keyboard entry. One of my pet projects & is making computers say Mantras, and idea proposed by & Edsger Dijkstra many years ago. Tibetan Buddhists use mechanical prayer & wheels to pray more quickly and efficiently. & Japanese Buddhists of the Amida sect believe & that anyone who says "Amida" with pure & heart will go to heaven, so they say it as many times as possible & in hopes of forgetting and saying it with pure heart once in their lives. This Mantra system combines these ideas just in case they & may be right. Who can have purer heart than a & computer? If you run a Mantra system often, perhaps & your computer will also forget and therefore insure your place in heaven. While (Kbd:Hit==False) While (Counter < 40 And Kbd:Hit==False) Mantra:Show(Here) ++Counter While (Counter > 0 And Kbd:Hit==False) Win:Del --Counter Kbd:Bye Return Mantra:Show (Level) New (Row,Col) Row = Num:Rand(2,10) Col = Num:Rand(2,60) The JORF Manual (Shareware Disk Version) 230 Win:Add ("Om",Row,Col,0,0,Level) Am I a butterfly that dreams I am a computer? Or am I a computer that dreams I am a Butterfly? Return(Ok) Chapter Five - JORF Functions 231 Num:Sqrt Function Num:Sqrt ( Num ) Purpose Returns the square root of Num. Returns Square root of Num. See Also Num:Pow. Notes Returns the square root of Num. The return value is an integer only if it fits. If it is fractional, it is a floating point value. The square root of zero is returned as zero. The JORF Manual (Shareware Disk Version) 232 Num:Str Function Num:Str ( Number, Format, Base, Width ) Purpose Convert number to a formatted string. Returns Returns the formatted string. See Also To:Num. Notes Converts and formats a number making it a string. This is the opposite of To:Num. You can use the Base to change the number base of the conversion. The default is 10 for decimal. You can 16 for hexadecimal, 8 for octal, or any other number for other numbering bases. You can use the Format to apply a format to the number. The formatter is a string with a mask for the number. Available digits in the string are: # Writes a numeric digit 0 Writes 0 place holder or the numeric digit - Writes a - sign if number is negative + Writes a + sign if positive, - if negative . Decimal point , Commas will be printed in the locations specified. : Any other character will be printed as is. If you specify a width, the returned number will be right justified with spaces to the specified width. This is useful for formatting a number in reports, and is used by the Window management system for on-screen formatting of numbers. Some examples of formatters: Number Formatter Result 1234567.89 "#,###,##0.00" "1,234,567,89" 0 "#,###,##0.00" "0.00" 0 "#,###,###" Null 1234 "00:00" "12:34" Example The Binary.J sample program formats numbers in base 2. Binary:Start New Char Chapter Five - JORF Functions 233 Win:Add ("BINARY VALUES", 4, 4, 19, 60, Here) For (Char = 0 Thru 255) If (Char > 0 and (Char % 16 == 0)) Win:Pause If Key:Got == "Esc_Key" Break Str:Put(" Character= {To:Str(Char,'000')} Symbol= ") Char:Put(Char) Str:PutLine(" Binary= {To:Str(Char,'0000 0000',2)}") If Key:Got != "Esc_Key" Win:Pause Jorf:Exit The Payment.J sample program uses a number of formatters to format dollar and percentage amounts. Class:Payment (Amt,Yrs,Intr,Pmt,Pmt50,Yrs50) Payment:Start New (Payment:Pmt) Win:Add ("Loan Payment Calculator",5,20) String:"Calculate your loan payment amount and years" String:"to pay if you added just $50 to the payment." String: String:"Press the TAB key to get from one field to" String:"the next. ENTER will end the program." Input:"&Loan Amount ", Row:7 Col:5 Wid:14 Field:"Pmt->Amt", After:"Payment:Calc(Pmt)" Format:"###,###,###.00", Type:"Numeric" Input:"&Years to Pay ", Row:8 Col:5 Wid:3 Field:"Pmt->Yrs", After:"Payment:Calc(Pmt)" Format:"###", Type:"Numeric" Input:"&Percent Interest ", Row:9 Col:5 Wid:8 Field:"Pmt->Intr", After:"Payment:Calc(Pmt)" Format:"00.0000%", Type:"Numeric" Input:"Payment ", Row:10 Col:5 Wid:14 Field:"Pmt->Pmt", Before:"Return(Null)" Format:"###,###,###.00", Type:"Numeric" Input:"Adding just $50 ", Row:12 Col:5 Wid:14 Field:"Pmt->Pmt50", Before:"Return(Null)" Format:"###,###,###.00", Type:"Numeric" Input:"Reduces the years to" Row:13 Col:5 Wid:3 Field:"Pmt->Yrs50", Before:"Return(Null)" Format:"###", Type:"Numeric" The JORF Manual (Shareware Disk Version) 234 Button:" &Done ", Row:15, Col:16 Return(Ok) Payment:Calc(Pmt) New (Periods,Per_Intr,Payment,Months50) Pmt->Pmt = 0 If (Pmt->Intr > 0 And Pmt->Yrs > 0) Periods = Pmt->Yrs*12 Per_Intr = Pmt->Intr/12/100 Payment = (Pmt->Amt*Per_Intr) / (1-Num:Pow(1+Per_Intr,(-Periods))) Payment = Num:Int((Payment+.005)*100)/100 Pmt->Pmt = Payment Pmt->Pmt50 = Payment+50 Months50 = Num:Log(Pmt->Pmt50/(Pmt->Pmt50-Pmt->Amt*Per_Intr)) Months50 = Months50/Num:Log(1+Per_Intr) Pmt->Yrs50 = Num:Int((Months50/12)*10)/10 Win:Dsp Return (Ok) Special Note Some countries use a comma-decimal format where the comma marks the decimal point and a period is the thousands indicator. To accommodate these countries, JORF has an INI file setting to change the default display format to use the comma-decimal format. Even when changed, however, all numeric formatters for Num:Str must be in the American period-decimal style. Also, decimal numbers written in the program must also be period-decimal style. This allows programs to be portable, because the code does not need to change to accommodate users who wish to use the comma-decimal style. For an example of comma-decimal formatting, change your the Decimal setting in your INI file to "Decimal=,", then run the Payment.J sample program. Note that in the program the number .005 is expressed in period-decimal format, even though the resulting calculation is displayed in comma decimal format. Decimal Number Formatter Result Period 1234.56 "#,##0.00" "1,234.56" Comma 1234.56 "#,##0.00" "1.234,56" Period .005 "0.0000" "0.0050" Comma .005 "0.0000" "0,0050" Chapter Five - JORF Functions 235 Ok Function Ok Purpose None. Returns 1 (integer one). See Also True. Notes This value allows you create readable "Endless" While loops by saying While Ok. The JORF Manual (Shareware Disk Version) 236 Rep:Add Function Rep:Add ( Title, Row, Col, Len, Wid, Level, Def ) Purpose Write a report or document. Returns None. See Also File:Print. Notes The future of this function is bright, but currently it is but a shadow of what will come. The job here is to create a report generating system as easy as the screen system handled item the Win:Add command. The parameter Title is used only for the status box that will shows page and line is currently being generated. The parameters Row, Col, Len and Wid help define the page size. The last parameter Def for definition is usually the report definition in an indented section below this command. The report is always written to the file JREPORT.LST which then can be printed using File:Print. Like Win:Add, there are several key words used to define report elements. Header A page header item Footer A page footer item Next Method to get the next record Item An Item on the report Text A multiline text in the report If the operator presses the Esc_Key while a report is being generated, the process will be aborted, the file erased and null returned. Checking file existence is a good test of whether the Rep:Add finished normally. Still to be completed is multiple level processing (which will be done using indented sections, of course) and support for printer drivers. Please contact The JORF Company for further changes and upgrades to this command. Chapter Five - JORF Functions 237 Example This next example shows a normal report format. This report lists contact names one after the other. It contains a header and a footer. Contact:List New (Dest) Mem:Ptr->IndexName = "FullName" Time:Get(Mem:Ptr) Mem:Ptr->Page=1 Dest=Jorf:Printer() If (Dest) Win:Add("Printing") Printing . . . Contact:SetFile(Here) Rep:Add ("Contact Listing", 5, 5, 60, 75,Here) Header:"'Contact Listing Report'" NewRow:1 Col:30 Header:"'Page '+Mem:Ptr->Page" NewRow:1 Col:1 Header:"'Date '+Mem:Ptr->SDate" Col:50 Header:"Str:AtSet(Null,1,'-',80)" NewRow:1 Col:1 Next:"Struct:Next('Contact', Mem:Ptr->IndexName, Mem:Ptr->Contact)" Item:"Mem:Ptr->Contact->FullName" NewRow:2 Col:1 Len:20 Item:"Mem:Ptr->Contact->Company " Col:22 Len:32 Item:"Mem:Ptr->Contact->WorkPhone" Col:52 Len:28 Item:"Mem:Ptr->Contact->Addr1" NewRow:1 Col:5 Len:30 Item:"Mem:Ptr->Contact->Addr2" NewRow:1 Col:5 Len:30 Item:"Mem:Ptr->Contact->Addr3" NewRow:1 Col:5 Len:30 Item:"Null" NewRow:1 Col:5 Len:30 Footer:"'Continued on Page '+Mem:Ptr->Page+1" Row:56 Col:1 File:Print("Jreport.lst",Dest) Return (Ok) The JORF Manual (Shareware Disk Version) 238 If you skip the page definition, the report will print without headers or footers. You can use this to print continuous forms. Contact:ContinLabels(Flag) New (Dest,CurrContact) Dest=Jorf:Printer() Win:Add("Printing") Printing . . . Contact:SetFile(Here) CurrContact = Mem:Ptr->Contact Mem:Ptr->OneContact= CurrContact Mem:Ptr->Contact = Null | Report format for Continuous labels, 6 lines, 1 line between | Rep:Add ("Continuous Labels") Next:"Contact:Nextlabel(Flag)" Item:"'('+Mem:Ptr->Contact->MailCode+')'" NewRow:1 Col:26 Wid:12 Before:"Mem:Ptr->Contact->MailCode!=Null" Item:"" NewRow:1 Col:26 Wid:12 Before:"Mem:Ptr->Contact->MailCode==Null" Item:"Mem:Ptr->Contact->FullName" NewRow:1 Col:1 Wid:40 Item:"Mem:Ptr->Contact->Company" NewRow:1 Col:1 Wid:40 Before:"Mem:Ptr->Contact->Company!=Null" Item:"Mem:Ptr->Contact->Addr1" NewRow:1 Col:1 Wid:40 Item:"Mem:Ptr->Contact->Addr2" NewRow:1 Col:1 Wid:40 Item:"Mem:Ptr->Contact->Addr3" NewRow:1 Col:1 Wid:40 Item:"" NewRow:1 Before:"Mem:Ptr->Contact->Company==Null" File:Print("JREPORT.LST",Dest) Mem:Ptr->Contact=CurrContact Return(Null) Chapter Five - JORF Functions 239 This last example shows how you can read an ASCII text file to feed a text item in the report. The text key word takes the name of a JORF pointer that holds the text to use for a format. Lines in that text may contain JORF variables in curly braces. Contact:MergeLetter New (Dest,Letter,CurrContact) Time:Get(Mem:Ptr) Letter=File:Load(Contact:GetLetter) If (Letter!=Null) Dest=Jorf:Printer() If (Dest) CurrContact=Mem:Ptr->Contact Mem:Ptr->Contact=Null Win:Add("Printing") Printing . . . Rep:Add ("Merge Letter", 5, 5, 60, 75,Here) Header:"" Row:1 Next:"Contact:NextRecord('Next')" Text:"Letter" File:Print("JREPORT.LST",Dest) Mem:Ptr->Contact=CurrContact Return (Ok) The JORF Manual (Shareware Disk Version) 240 Return Function Return (Value ) Purpose Return a value. Returns None. Notes Methods may return a single value using this command. If no value is specified, null is returned. A method that ends without an explicit Return is the same as Return (Null). If more than one value needs to be returned, the parameters used to call the function may be changed. Return may be used at any time, including If statements and While loops. This will end execution of the current method and return control to the calling method. Chapter Five - JORF Functions 241 Rule:Add Function Rule:Add ( RuleStructure ) Purpose Add a new Rule. Returns None. See Also Key:Add. Notes RuleStructure must be a structure with the elements Obj, Att, Val, Prob, Ptr, Fnd (Found), and KLen (Key Length). The last two elements are used by Rule:Find to get next rule in a series. The element Str used by Key:Find are replaced here by Att and Val. Adds rule valued Obj, Att and Val, with the associated data in Ptr (Pointer). The rule may be found again by doing a partial or whole rule search on RuleStructure. Example The ISA.J source file demonstrates both forward and backward searching using the Rule system. It is an older sample program and so has pretty primitive window handling. The JORF Manual (Shareware Disk Version) 242 Rule:Del Function Rule:Del ( RuleStructure ) Purpose Delete a Rule in the Data Base. Returns None. Sets RuleStructure->Fnd to True if Rule was deleted. See Also Key:Del. Notes Deletes an existing rule. This command may be called with a partial rule, in which case it will delete the first rule that begins with that value. It is highly recommended that this command be called with a complete rule to insure that the correct entry is deleted. After a rule is deleted, you can still use Rule:Next go the "next" rule. Chapter Five - JORF Functions 243 Rule:Find Function Rule:Find ( RuleStructure ) Purpose Find a Rule in the Data Base. Returns None. Sets RuleStructure->Fnd to True if Rule was found. See Also Rule:Add. Notes Find a rule. In this function, parameters may be empty, in which case the first matching index entry will be returned. Parameters must be empty from left to right, that is, if Att has a value then Obj must also have a value. If a "hole" is left, then nothing will ever be found. When a rule is found, the structure will be filled with the values of that rule and Fnd will be set to True. If Rule:Next is called with these values set, then the next rule value is returned. This process may be continued until the value of the current rule does not match the value of the original partial rule. This length is put in KLen after every successful search and may be modified. Example The HAIKU.J uses this function to save the word table info. The JORF Manual (Shareware Disk Version) 244 Rule:Next Function Rule:Next ( RuleStructure ) Purpose Find the next Rule in sequence. Returns None. Sets RuleStructure->Fnd to True if Rule was found. See Also Rule:Find. Notes If RuleStructure->KLen is zero, this works just like Rule:Find. If not zero, this command finds the next rule in a sequence. This process may be continued until the value of the current rule within the Klen changes. Values for Klen are: 0 Rules with the same Type match 1 Rules with the same Type+Obj match 2 Rules with the same Type+Obj+Att match 3 Rules with the same Type+Obj+Att+Prob+Val match Example See Rule:Add. Chapter Five - JORF Functions 245 Rule:Prev Function Rule:Prev ( RuleStructure ) Purpose Find previous Rule in sequence. Returns None. Sets RuleStructure->Fnd to True if Rule was found. See Also Rule:Next. Notes This command is the opposite of Rule:Next. The JORF Manual (Shareware Disk Version) 246 Str:Aft Function Str:Aft ( String, CharList ) Purpose Get substring starting with the first character not specified in CharList. Returns The substring. See Also Str:AtChar. Notes Skips over characters specified, and returns the string after those characters. The most common example is to specify the string after any leading spaces. This command is the functional equivalent of the C language strninset(). The return value is the substring, not the position. Example See Jorf:Write. Chapter Five - JORF Functions 247 Str:At Function Str:At ( String, Position, Length ) Purpose Get a substring at specified position in String. Returns The substring. See Also Str:In. Notes Returns the substring at the specified position and length. JORF does not think of single characters as integers, as in BASIC, C and Pascal. Instead, JORF sees characters as one letter strings. The first character of the string is one (1) and the last character is the return value of Str:Len. A negative Position indicates an offset from the right (end) of the string. A negative Length just counts backward. A Position or Length that are out of bounds returns whatever part of the string is in bounds. Example See Event:Add. The JORF Manual (Shareware Disk Version) 248 Str:AtChar Function Str:AtChar ( String, CharList ) Purpose Get a substring starting with one of characters in CharList. Returns The substring. See Also Str:In. Notes Get a substring starting with one of the specified characters. To look for a substring within a string, use Str:In. Returns the substring, not the position. Chapter Five - JORF Functions 249 Str:AtCut Function Str:AtCut ( String, Position ) Purpose Get a truncated version of string. Returns The truncated string. See Also Str:AtDel. Notes Truncates String at Position. This command is functionally the same as: Str:AtDel (String, Pos, Str:Len(String)-Pos) If Position is less than one, or greater than the length of String, then nothing will change. The JORF Manual (Shareware Disk Version) 250 Str:AtDel Function Str:AtDel ( String, Position, Count ) Purpose Returns a version of String with deleted characters. Returns The modified string. See Also Str:AtCut. Notes Deletes Count characters from a string at Position. If Count is zero, or exceeds the length of the string, then the string will be truncated at Position. If Position is less than one, or greater than the length of String, then nothing will change. Chapter Five - JORF Functions 251 Str:AtPut Function Str:AtPut ( String, Position, InsertString ) Purpose Insert a substring within string. Returns The modified string. See Also Str:AtSet. Notes Inserts InsertString into String at Position. If Position is less than one, or greater than the length of String, then nothing will change. This command will not overwrite existing characters. Instead, it expands the string to fit the new characters. To replace characters, first use Str:AtDel. The JORF Manual (Shareware Disk Version) 252 Str:AtSet Function Str:AtSet ( String, Position, InsertString, Count ) Purpose Sets a repeated value into String. Returns The modified string. See Also Str:AtPut. Notes Inserts InsertString, Count times, into String at Position. If Position is less than one, or greater than the length of String, then nothing will change. This command will not overwrite existing characters. Instead, it expands the string to fit the new characters. To replace characters, first use Str:AtDel. This command is used to place a repeated pattern in a string. It also may be used to create a buffer full of a known value. Use Str:AtSet(Null,1,"*", 15) to create '***************'. To create a buffer full of spaces use Str:Pad, or nulls with Str:NPad. Chapter Five - JORF Functions 253 Str:In Function Str:In ( String, Substring ) Purpose Returns the position of Substring in String. Returns A numeric position. See Also Other String functions. Notes If Substring is not found then returns zero. The search is always insensitive to letter case. The first position is 1 and the last position is Str:Len(String)- Str:Len(SubString). A return value of zero or null indicates the substring is not found in string. Examples: Str:In ("Josephine", "ph") Result 5 Str:In ("Festus", "f") Result 1 Str:In ("Bear", "EAR") Result 2 Str:In ("Josephine", "Z") Result 0 The JORF Manual (Shareware Disk Version) 254 Str:Len Function Str:Len ( String ) Purpose Get the number of characters in String. Returns The number of characters in String. See Also Text:Len. Notes Returns the number of characters in a string. Also returns the string length of all JORF data types. String String Length Number Length of number formatted as a string Date Length of date formatted as a string Time Length of time formatted as a string Structure 0 Array 0 Text Length of line pointed to by text Chapter Five - JORF Functions 255 Str:NPad Function Str:NPad ( String, Length ) Purpose Pad the end of String with nulls until it is the specified Length. Returns The modified String. See Also Str:Pad. Notes Not commonly used for anything but writing specialized file formats. Many file formats require fields that are null padded, instead of space padded. Use this command to null pad your strings. Once a string is null padded, most JORF functions will reconvert the string back to it's smallest format. You should use this command just prior to writing a string or buffer to file. The JORF Manual (Shareware Disk Version) 256 Str:Pad Function Str:Pad ( String, Length ) Purpose Pad the end of String with spaces, until it is the specified Length. Returns The modified String. See Also Str:NPad. Notes Commonly used to format consecutive strings for output on the screen or printer. By padding, you can column align values. If the string is too long, this command will truncate it to the Pad length. Chapter Five - JORF Functions 257 Str:Print Function Str:Print ( Printer, String ) Purpose Direct serial or parallel port output of a String. Returns The modified String. See Also Str:NPad. Notes This command became obsolete for printing as of version 2.0 of the JORF Interpreter because MS-Windows does not adequately support printing anything less than a data file with a full page of output. There are rare circumstances where programmers may still require direct access to the output ports.. For instance, to auto-dial a modem requires that you submit the AT commands directly to the modems serial port. For this purpose, the Str:Print has been restored to communicate directly with an output (serial or parallel) prot. This command prints String to the designated port. The Port must be Prn, Aux, LPT1, LPT2, COM1, or COM2 to indicate default printer, auxiliary port, line printer one and two, and serial printer one and two. Internally, the interpreter uses both BIOS and DOS calls to access the port. You cannot set the speed of a serial port using the JORF Interpreter. Instead, use the DOS MODE command. To set up a Hayes compatible 2400 baud modem for auto-dialing, you need to execute: C>Mode Com1:2400,n,8,1,p If this command works for you, you should put it in your autoexec.bat file so it is executed when your computer boots. In theory, this function supports COM1 through COM9, and LPT1 through LPT9. In practice, the last port accessed may be limited by your computer, Windows or DOS. The JORF Manual (Shareware Disk Version) 258 Str:Put Function Str:Put ( String ) Purpose Put a string on the window. Returns None. See Also Str:PutLine. Notes Outputs a JORF data pointer as a string to the current window at the current cursor position. You can use this function to display the data from any JORF type except structures. To display a structure, you must display the elements of that structure independently. You can mix text and variables two ways. One is to assemble them at print time by adding them together. Jorf:MyPrint(Var1,Var2) Str:Put("Var1 is "+Var1+" and var2 is "+Var2) Return (Ok) The other way is to surround variables in curly brackets to indicate that they are magic spots. This method is faster, because magic spot processing is faster than string concatenation. This method will does not work on windows where Win:Ptr->Magic is FALSE because Win:Ptr->Magic controls whether magic spots are interpreted. Jorf:MyPrint(Var1,Var2) Str:Put("Var1 is {Var1} and var2 is {Var2}") Return (Ok) This function is buffered for speed. Calling this function sets the internal buffer, but the buffer is not shown on the screen until the line is finished. You can force a display by changing to another line using Move:To or by ending the line using Str:PutLine. Chapter Five - JORF Functions 259 Str:PutLine Function Str:PutLine ( Line ) Purpose Put string on window, then go to next line. Returns None. See Also Str:Put. Notes Outputs a line to the current window, moves the cursor to the next line. This command differs from Str:Put because it completes the line by moving the cursor. This function will re-display the entire text row in the window. The JORF Manual (Shareware Disk Version) 260 Str:Rpad Function Str:Rpad ( String, Length ) Purpose Pad the right side of String with spaces, until it is the specified Length. Returns The modified String. See Also Str:Pad. Notes Like Str:Pad this function is commonly used to format stings, especially numbers where right justification is desired. By padding, you can column align values. If the string is too long, this command will truncate it to the specified length. Chapter Five - JORF Functions 261 Struct:Find Function Struct:Find ( Class, Index, Value ) Purpose Find a structure using an automatic index. Returns Structure. See Also Struct:Next, Key:Find. Notes When you define a structure with automatic indexes the interpreter will automatically add, change and delete that index. This command allows you to find structures that have previously been stored using this index. Set Class to the class name, the Index to the name of the field that is indexed, and the Value to the value you want to find. If the search value is null, this command returns the first item in the index. Example The FILTER.J sample program is the simplest data base of all. The JORF Manual (Shareware Disk Version) 262 Struct:Next Function Struct:Next ( Class, Index, Value ) Purpose Find the next structure in sequence. Returns Structure. See Also Struct:Find. Notes If Value is null this command finds the first structure in the file. Each subsequent call finds the next record in sequence. This function is widely used for Window Lists where the Next command is used to find the next record in the list. If there are no more records in the index, this command returns null. Chapter Five - JORF Functions 263 Struct:Prev Function Struct:Prev ( Class, Index, Value ) Purpose Find the previous structure in sequence. Returns Structure. See Also Struct:Find. Notes If Value is null this command finds nothing - not the last structure in the index which is what you might expect. This function is widely used for Window Lists when you use the up arrow to go up through a file. If the Value was already at the first record in the index, this function returns null. The JORF Manual (Shareware Disk Version) 264 Switch/Case/Else Function Switch/Case/Else Purpose A conditional branch. Returns None. See Also If/Else. Notes A conditional Branch. Tests the value of a parameter and executes indented code sections based on that value. Switch ( TestValue ) Case Value1 Case Value2 Performs this section if TestValue is Value1 OR Value2 Else If no Case was valid this section performed. Tests a value and performs commands in indented sections. This command was introduced for the C language, but was not robust. I have strengthened the command by eliminating the need for explicit Break commands. I have changed "Default" to Else. And I allow more complex processing on Case lines. The Switch command does not need a parameter following. If the parameter is absent, the Case lines are expected to be logical expressions that can be evaluated. If the parameter is present, the parameter is check against the expression in the Case line. Break may not be used, even by hopeless C programmers like myself who put them in anyway. It was never robust to partially reuse code sections and K&R must not have realized the ramifications when they created the C language switch command. They required an extra key word for the common case and promoted the unwise programming practice of allowing the program flow to "fall" into another routine. Chapter Five - JORF Functions 265 Examples The Switch command is used to replace multiple If/Else statements. It checks a condition, and compares it to various Case clauses. It executes the indented section under the appropriate Case. It also has an Else clause, which works just like the else in an If statement. For example: Is Replaced By If (A=2) Switch (A) B=A+C Case 2 Else B=A+C If (A=3) Case 3 B=A+D B=A+D Else Case 4 If (A=4) B=A+E B=A+E Else Else B=A B=A Case functions may be stacked. Switch (Key) Case 'a' Case 'A' Say 'Key is A' Case 'b' Case 'B' Say 'Key is B' Else Say 'Key is not A or B' The Switch function is neater and easier to use than multiple If/Else functions. The condition for the switch command may be omitted, and the Case commands may be complex comparisons. Switch Case (Key>='a' && Key<='Z') Case (Key>='A' && Key<='Z') Say 'Key is a Letter' Case (Key>='0' && Key<='9') Say 'Key is a Number' Else Say 'Key is Something Else' The JORF Manual (Shareware Disk Version) 266 Text:Add Function Text:Add ( Line, Text ) Purpose Append Line to the bottom of Text. Returns Text. See Also Line:Inp, Win:Add. Notes Appends to existing text, or creates a new text. This command is commonly used to create paragraphs of text for output to the screen or printer. The return value is a JORF Pointer to text. This is a fascinating data type because it has two natures: A Pointer to text points to a string value for the specific line of text, and a text value that is linked to all the other lines of the text. This is a little confusing. Basically String functions will bring out the string nature of the current line, and Text functions will allow you to work with the text nature of a Text pointer. Adding lines to text is done internally, and if you want the new lines on a displayed text field to be displayed you must use Win:Dsp after adding. Text is "sparse" in memory, meaning that if it is too long, only portions are in RAM. The remainder of the text is stored on disk. If you are creating a large chunk of text, it will be swapped to the temporary file. If you later store the text in a data file, there may be considerable delay as the text is copied from the temporary swap file to your permanent file. For this reason, you may benefit from writing the first line of text to your destination file as it is created. This insures that the entire text is written to the final destination file, eliminating later delays. Text is stored in 4K chunks. When you reference a line of text, the first 4K and the 4K chunk that contains the line is loaded. The chunks are indexed so that obtaining the last line of text does not require reading all chunks. However, inserting a new line, or deleting a line requires that all subsequent chunks be rewritten. That is why the system slows down for line insert and line delete functions on text over 10K of memory. Chapter Five - JORF Functions 267 The maximum number of lines allows is 32K. However, speed and storage requirements will make any text with more than 2000 lines pretty pokey and not advised. Each line of the text may be up to 10K bytes long. The 10K limit is imposed by a bug in the Borland library in failing to dependably allocate large blocks of memory. If this bug is fixed, the limit may go up to the JORF language design goal of 32K bytes per line. Warning: If you are building a multi-line text, and you get the parameters to Text:Add backward, your text will not be created, and you will only see the last line you added. Example See the HAIKU.J sample program. The JORF Manual (Shareware Disk Version) 268 Text:At Function Text:At ( Text, LineNumber ) Purpose Get a specific line of Text. Returns The line of Text. See Also Text:Pos. Notes Returns the line of Text at LineNumber. If Text is not a block of text, it is treated as a single line of text. If the LineNumber is greater than the length of the text this function returns null. The first line of text is at Text:At(Text,1). The last line of text is at Text:At(Text,Text:Len(Text)). Example See Text:Bot Chapter Five - JORF Functions 269 Text:Bot Function Text:Bot ( Text ) Purpose Get the last line of a block of text. Returns The last line of Text. See Also Text:Top, Text:Next, Text:Len. Notes Returns the last line of Text. If Text is not a multiple line text block, then returns Text as if it were a one line text block. Example The following program demonstrates the text commands. Note how Text:Top and Text:Bot return the top and bottom of the whole method. To find the top of the block of text, check the number of leading spaces. Text:Start | Sample for Text Functions Text:Sample This text was passed to to a method because: a) The method call needed a parameter b) The text was indented Return Text:Sample Text New Win1, Win2 Win1->Text = Text Win1->Row = 2 Win1->Col = 2 Win:Add (Win1) Win2->Row=(-2) Win2->Col=(-2) Win2->Len=11 Win2->Wid=40 Win:Add (Win2) Str:PutLine ("Text = "+Text) Str:PutLine ("Text:Len = "+Text:Len (Text)) Str:PutLine ("Text:Wid = "+Text:Wid (Text)) Str:PutLine ("Text:Top = "+Text:Top (Text)) Str:PutLine ("Text:Bot = "+Text:Bot (Text)) Str:PutLine ("Text:At 2 = "+Text:At (Text, 2)) Text = Text:Next (Text) Str:PutLine ("Text:Next = "+Text) The JORF Manual (Shareware Disk Version) 270 Text = Text:Next (Text) Str:PutLine ("Text:Next = "+Text) Text = Text:Next (Text) Str:PutLine ("Text:Next = "+Text) Text = Text:Next (Text) Str:PutLine ("Text:Next = "+Text) Str:PutLine ("Text:Pos = "+Text:Pos (Text)) Text = Text:Prev (Text) Str:PutLine ("Text:Prev = "+Text) Win:Pause Return Chapter Five - JORF Functions 271 Text:Len Function Text:Len ( Text ) Purpose Get number of lines in Text. Returns Returns number of lines. See Also Text:Len, Text:Wid. Notes If Text is not a text block, it will be treated as a single line. Example See Text:Bot The JORF Manual (Shareware Disk Version) 272 Text:Next Function Text:Next ( Text ) Purpose Gets the next line of Text. Returns A Jorf Pointer to the next line of Text. See Also Text:Prev, Text:Len. Notes Returns the next line of Text. If Text is on the last line, or is not a block of text, this function returns null. Example See Text:Bot Chapter Five - JORF Functions 273 Text:Pos Function Text:Pos ( Text ) Purpose Returns the line number of Text. Returns The previous line of Text. See Also Text:At. Notes Returns the line number of Text. If Text is on the first line, or is not a block of text, this function returns 1. Example See Text:Bot The JORF Manual (Shareware Disk Version) 274 Text:Prev Function Text:Prev ( Text ) Purpose Get previous line of Text. Returns The previous line of Text. See Also Text:Next. Notes Returns the previous line of Text. If Text is on the first line, or is not a block of text, this function returns null. Example See Text:Bot Chapter Five - JORF Functions 275 Text:Top Function Text:Top ( Text ) Purpose Get a Jorf Pointer to the top of a block of text. Returns A Jorf Pointer to the first line of a block of text. See Also Text:Bot. Text:Next. Notes Returns the first line of Text. If Text is not a text block, then Text is returned because it is treated as a one line text block. Example See Text:Bot The JORF Manual (Shareware Disk Version) 276 Text:Wid Function Text:Wid ( Text ) Purpose Get the width necessary to display this block of text. Returns The width of the widest line of Text. See Also Str:Len. Notes Returns the width of the widest line of Text. The common use of this function is to obtain the width of a text box for display or printout purposes. To insure speed, only the first 60 lines are checked for width. Example See Text:Bot Chapter Five - JORF Functions 277 Time:Add Function Time:Add ( Time, Minutes, Hours, Seconds ) Time:Add ( Time, "HH:MM:SS" ) Purpose Add the specified Minutes, Hours or Seconds from the Time. Returns A time. See Also Time:Sub, Date:Add. Notes This is a very specialized command that helps you calculate one minute after or one hour after a time. Note the parameters are not in smallest-to-largest order, but feature seconds last because that parameter is not often set. There is currently no logic overflow for when you set a time past or before midnight. The JORF Manual (Shareware Disk Version) 278 Time:Get Function Time:Get Purpose Get system Time. Returns A JORF pointer with the current system time. See Also Time:Set. Notes There is an internal data type for the time Conversion to this type is done using the To:Time function. Conversion from this types done using Time:Str. These functions are paralleled for date. Chapter Five - JORF Functions 279 Time:Set Function Time:Set ( Time ) Purpose Set DOS clock to the specified date. Returns None. See Also Date:Set, To:Time. Notes Sets the DOS time. Time should be the result of the To:Time function. You can also specify a string value in the form of HH:MM. Setting the DOS time and date does not always affect the computer's system clock. To permanently change the time and date on your computer, you may have to use a utility program. Network computers often get their date and time reset from the network file server. The JORF Manual (Shareware Disk Version) 280 Time:SetFmt Function Time:SetFmt ( FormatStructure ) Purpose Changes the default time string, and AM/PM indicator for Time:Str. Returns None. See Also Time:Str, Date:SetFmt. Notes The structure may be any structure with the elements specified below. The Element values are parsed and sorted in an internal static array. Changing the elements after setting them does not change the internal array until you call Time:SetFmt again. This function does not return any values, but sets up values for later use by Time:Str. The structure values are as follows: FormatStructure->Format | Default MM/DD/YY format FormatStructure->A1 | The name for AM FormatStructure->A2 | The name for PM Chapter Five - JORF Functions 281 Time:Str Function Time:Str ( Time, Format ) Purpose Formats the time according to format. Returns A formatted string. See Also Time:Get, Date:Str. Notes The specified time should be the result of the To:Time function that returns JORF pointer with an internal date value. (The internal value stores the time as a long integer value of the number of hundredths of seconds since midnight. The format is a string saying how to format the date. The following are special character within the format string: Time Formatters h = Hours Caps is military time _h = Hours, space in front Caps is military time hh = Hours, zero in front Caps is military time m = Minutes Caps is ignored _m = Minutes, space in front Caps is ignored mm = Minutes, zero in front Caps is ignored s = Seconds Caps is ignored _s = Seconds, space in front Caps is ignored ss = seconds, zero in front Caps is ignored a = am or pm Caps means AM or PM Time in "Military Time" is based on a 24 hour clock from 00:00 to 23:59. When not in military time, the hour after midnight is 12:00 AM to 12:50 AM, and noon is 12:00 PM. Any other characters are retained as-is, including other letters. The following examples show how the time 14:10 would be formatted: Time:Str(Time,"h:mm a") result "2:10 pm" Time:Str(Time,"hh:mm A") result "02:10 PM" Time:Str(Time,"HH:MM") result "14:10" Time:Str(Time,"H") result "14" Time:Str(Time,"h") result "2" The JORF Manual (Shareware Disk Version) 282 You can easily change the AM/PM indicator using the Time:SetFmt function. If the format is omitted, the default format of "HH:MM" is used. This default can be changed using Time:SetFmt. Chapter Five - JORF Functions 283 Time:Sub Function Time:Sub ( Time, Minutes, Hours, Seconds ) Time:Sub ( Time, "HH:MM:SS" ) Purpose Subtract the specified Minutes, Hours or Seconds from the Time. Returns A time. See Also Time:Add, Date:Sub. Notes This is a very specialized command that helps you calculate one minute before or one hour before a time. Note the parameters are not in smallest-to-largest order, but feature seconds last because that parameter is not often set. There is currently no logic overflow for when you set a time past or before midnight. The JORF Manual (Shareware Disk Version) 284 Time:Ticks Function Time:Ticks Purpose Gives an accurate timing mechanism. Returns The number of ticks since midnight. See Also Time:Get. Notes Returns the number clock ticks since midnight. This may be used to time methods and program processes. This allows you to time operations with greater precision than the seconds in the Time:Get command allows. Currently there are 18 ticks per second on all DOS and Windows based systems. Chapter Five - JORF Functions 285 To:ASCII Function To:ASCII ( String ) Purpose Get ASCII value of first character of String. Returns Returns the ASCII decimal value. See Also To:Char. Notes Converts a letter to its ASCII decimal value. For instance To:ASCII "A" returns 41. Generally String contains only one character, but can be a word or line of text. The JORF Manual (Shareware Disk Version) 286 To:Caps Function To:Caps ( String ) Purpose Capitalize a string. Returns Returns the capitalized string. See Also To:Ucs. Notes Insures that any character following a space in String is an upper case letter. Does not affect words or acronyms that are already in capital letters. This is used to change the appearance of strings for screen display. Chapter Five - JORF Functions 287 To:Char Function To:Char ( Value ) Purpose Returns a one character string with the letter designated by the ASCII Value. Returns Returns the one letter string. See Also To:ASCII. Notes For example, To:Char (41) returns "A". The JORF Manual (Shareware Disk Version) 288 To:Date Function To:Date ( Date, Format ) Purpose Converts a string to a date according to format. Returns A JORF pointer holding a date value. See Also To:Time, Date:Str. Notes Starting with version 2.1 of the JORF language, time and date are atomic JORF data types. This command converts a string into the more compact internal date format. (The date is stored as the number of days since the hypothetical 01/01/00). The format is a string saying how to format the date. The following are special character within the format string: Date Formatters s = String month Caps makes string upper case w = String weekday Caps makes string upper case n = Numeric weekday Caps is ignored m = Month Caps is ignored mm = Month, zero in front Caps is ignored d = Day Caps is ignored dd = Day, zero in front Caps is ignored y = Year Caps is ignored yy = Two digit year Caps is ignored yyyy = Four digit year Caps is ignored If the format is omitted, the default format is used. The default format is "MM/DD/YY". This format can be changed using Date:SetFmt. Chapter Five - JORF Functions 289 To:Int Function To:Int ( Num ) Purpose Returns the integer value of Num Returns Integer. See Also Num:Str. Notes This function truncates decimals, returning the next lower integer value for positive numbers, and the next higher integer for negative numbers. You can also create integer strings (which are often automatically converted to numbers) using the Num:Str function. The JORF Manual (Shareware Disk Version) 290 To:Lcs Function To:Lcs ( String ) Purpose Convert a string to lower case. Returns The lower case string. See Also To:Ucs. Notes Converts all characters, including initials and acronyms, to lower case. Chapter Five - JORF Functions 291 To:Num Function To:Num ( String, Base ) Purpose Convert String to its numeric value. Does not change items that are already numbers. Returns Returns the numeric value. See Also Num:Str. Notes This function is used to convert to strings and to format them. You can use another numbering Base for the conversion. If Base is omitted or does not have a numeric value, then BASE 10 is used. Use a Base of 16 for Hexadecimal, 8 for Octal, or any number from 2 through 36 for other bases. Strings may be integers, decimals and floating point numbers with "E" notation (ex. "3.24E-4"). This command does not change values that are already numbers, and may be used as a precautionary measure when the value might or might not have already been converted. Example The CALC.J program assembles numbers as character strings so that when you hit a new digit, that digit is appended to the number. When you hit a calculation key, like the plus sign (+) the string numbers must be converted to numeric numbers before adding. Class:Calc | Declare class Calc Entry | Current entry value Op | Last operation key Result | Result of last calc Calc:start New(Calc:Calc) Calc->Entry = "0" Calc->Result = "0" Mem:Ptr->Calc=Calc Event:Add(Null) Win:Add ("Calculator",0,0,8,17) Button:"&=", Row:8, Col:14, Wid:3, Len:1 Action:"Calc:Do('=')" The JORF Manual (Shareware Disk Version) 292 Input:"Res" Row:1, Col:2, Wid:11, Len:1 Field:"Mem:Ptr->Calc->Result" Before:"Null" Input:"Ent" Row:2, Col:2, Wid:9, Len:1 Field:"Mem:Ptr->Calc->Entry" Before:"Null" Input:"" Row:2, Col:15, Wid:1, Len:1 Field:"Mem:Ptr->Calc->Op" Before:"Null" HLine:"" Row:3 Button:"&C", Row:4, Col:2, Wid:3, Len:1 Action:"Calc:Do('C')" Button:"c&E", Row:4, Col:6, Wid:3, Len:1 Action:"Calc:Do('E')" Button:"e&Xit", Row:4, Col:10, Wid:3, Len:1 Action:"Calc:Do('X')" Button:"&/", Row:4, Col:14, Wid:3, Len:1 Action:"Calc:Do('/')" Button:"&7", Row:5, Col:2, Wid:3, Len:1 Action:"Calc:Do('7')" Button:"&8", Row:5, Col:6, Wid:3, Len:1 Action:"Calc:Do('8')" Button:"&9", Row:5, Col:10, Wid:3, Len:1 Action:"Calc:Do('9')" Button:"&*", Row:5, Col:14, Wid:3, Len:1 Action:"Calc:Do('*')" Button:"&4", Row:6, Col:2, Wid:3, Len:1 Action:"Calc:Do('4')" Button:"&5", Row:6, Col:6 , Wid:3, Len:1 Action:"Calc:Do('5')" Button:"&6", Row:6, Col:10, Wid:3, Len:1 Action:"Calc:Do('6')" Button:"&-", Row:6, Col:14, Wid:3, Len:1 Action:"Calc:Do('-')" Button:"&1", Row:7, Col:2, Wid:3, Len:1 Action:"Calc:Do('1')" Button:"&2", Row:7, Col:6 , Wid:3, Len:1 Action:"Calc:Do('2')" Button:"&3", Row:7, Col:10, Wid:3, Len:1 Action:"Calc:Do('3')" Button:"&+", Row:7, Col:14, Wid:3, Len:1 Action:"Calc:Do('+')" Button:"&0", Row:8, Col:2, Wid:3, Len:1 Action:"Calc:Do('0')" Button:"&.", Row:8, Col:6, Wid:3, Len:1 Action:"Calc:Do('.')" Button:"C&S", Row:8, Col:10, Wid:3, Len:1 Action:"Calc:Do('S')" Return (Mem:Ptr->Calc->Result) Calc:Do(KeyLetter) New (Calc) Calc=Mem:Ptr->Calc Switch KeyLetter Case "X" Jorf:Exit() Case "C" Calc->Result="0" Calc->Entry ="0" Calc->Op =Null Case "E" Calc->Entry ="0" Case "S" If (Calc->Entry!="0") Calc->Entry = 0-Calc->Entry Else If (Calc->Result!="0") Calc->Result = 0-Calc->Result Case "-" Chapter Five - JORF Functions 293 Case "+" Case "/" Case "*" Case "=" If (Calc->Entry!="0") Switch (Calc->Op) Case "-" Calc->Result = To:Num(Calc->Result) - To:Num(Calc->Entry) Case "+" Calc->Result = To:Num(Calc->Result) + To:Num(Calc->Entry) Case "*" Calc->Result = To:Num(Calc->Result) * To:Num(Calc->Entry) Case "/" Calc->Result = To:Num(Calc->Result) / To:Num(Calc->Entry) Else Calc->Result = Calc->Entry Calc->Entry = "0" Calc->Op = KeyLetter Else If Str:In("1234567890.",KeyLetter) If (Calc->Op == "=" Or Calc->Entry=="0") Calc->Entry = KeyLetter If (Calc->Op=="=") Calc->Op = Null Else Calc->Entry = Calc->Entry + KeyLetter Kbd:Put("Home_Key") Win:Dsp Return Ok The JORF Manual (Shareware Disk Version) 294 Special Note Some countries use the comma for a decimal point, and the period for the thousands indicator. You can make this the default by setting Decimal=, in the JORF.INI file (See appendix D). After setting this value, numbers stored as strings will be converted according to comma-decimal format. Sometimes, numbers stored as strings are in period-decimal format and need a special conversion. Number As Period decimal As Comma decimal "1,233.2" 1233.2 1.233 "1.233,2" 1.233 1233.2 To handle a value that was stored as a string in period decimal format, use To:Num(Value,"."). Using a period or comma as the Base causes a base 10 conversion with an override on the user's setting for the decimal format. This feature can also be used when reading decimal values from an ascii file that must be converted to numbers without regard to the user's Decimal= setting. When a user runs a program with "Decimal=,", only the user's input and output takes on the new format. All calculations and number formats in the JORF program code must be in period-decimal format. That way, the code is international, only what the user see's changes according to the INI file setting. Chapter Five - JORF Functions 295 To:Time Function To:Time ( Time, Format ) Purpose Converts a string to a time according to format. Returns A JORF pointer holding a time value. See Also To:Date, Time:Str. Notes Starting with version 2.1 of the JORF language, time and date are atomic JORF data types. This command converts a string into the more compact internal time format. (The time is stored as the number of seconds since midnight). The format is a string saying how to format the date. The following are special character within the format string: Time Formatters h = Hours Caps is military time _h = Hours, space in front Caps is military time hh = Hours, zero in front Caps is military time m = Minutes Caps is ignored _m = Minutes, space in front Caps is ignored mm = Minutes, zero in front Caps is ignored s = Seconds Caps is ignored _s = Seconds, space in front Caps is ignored ss = seconds, zero in front Caps is ignored a = am or pm Caps means AM or PM Time in "Military Time" is based on a 24 hour clock from 00:00 to 23:59. When not in military time, the hour after midnight is 12:00 AM to 12:50 AM, and noon is 12:00 PM. If the format is omitted, the default format is used. The default format is "HH:MM". This format can be changed using Time:SetFmt. The JORF Manual (Shareware Disk Version) 296 To:Ucs Function To:Ucs ( String ) Purpose Convert a string to UPPER CASE. Returns The UPPER CASE string. See Also To:Caps, To:Lcs. Notes Converts all characters, including initials and acronyms, to UPPER CASE. Returns the resulting string. Chapter Five - JORF Functions 297 True Function True Purpose Returns a value to indicate Logical True. Returns A JORF Pointer to the integer 1. See Also False. Notes Most programming language express results of logical equations as zero to indicate False, and one to indicate True. These values are called Boolean values. This function was created in the interest of program clarity. It simply returns the integer value one. The JORF Manual (Shareware Disk Version) 298 While/Break/Continue Function While/Break/Continue Purpose A Loop Returns None. Notes A loop. Tests the value of a parameter and executes indented code sections based on that value. While ( TestValue ) Does indented section until false Break Continue Tests a value and does commands in indented sections until that value is zero or false. The value is often a logical expression in parenthesis. While(Ok) is commonly used to indicate a loop that will be ended using the Break command. Break ends the execution of a While. Program flow will resume on the line following the loop. Continue ends execution of the current loop, returns control to the While command to test and executed the loop again if the condition remains valid. This command is used to simplify code within complex while loops. Chapter Five - JORF Functions 299 Examples The While statement creates a loop based on a condition. This loop is repeated as long as the condition is TRUE. A Break can be used to break out of the loop even if the condition is still True. A Continue is used to shortcut the loop, restarting the next iteration immediately. Counter=0 | Initialize Counter While (++Counter <= 5) | Increment Counter Rule:Find (Rule) | Find a next rule If (Rule->Fnd=Null) | If not found Break | break out of loop If (Rule->Ptr=Null) | If condition Null Continue | Skip rest of loop P=P+"-"+Rule->Pointer | Add Pointer Str:PutLine (P) | Show result The JORF Manual (Shareware Disk Version) 300 Win:Add Function Win:Add ( Title, Row, Col, Len, Wid, Level, Text ) Win:Add ( Title, Text ) Win:Add ( WindowStructure, Row, Col, Len, Wid, Level, Text ) Win:Add ( WindowStructure, Text ) Purpose Display a new Window on the screen. Returns None. See Also Chapter Four, Msg:Add, Move:To, Str:Put. Notes Without doubt, the most complicated library function. WindowStructure can contain the following elements: Row Top Row of Window Col Left Column of Window Len Number of rows inside window Wid Number of columns in window CurRow Cursor Row in Window CurCol Cursor Column in Window MouseRow Mouse Cursor Row in Window MouseCol Mouse Cursor Column in Window RowOff Rows that display is offset ColOff Columns that display is offset InpRow Row of Input Field InpCol Column of Input Field InpLen Length of Input Field InpWid Width of Input Field Text Text displayed in Window Type Window color or type Level Value of Here in method that is creating the window Magic TRUE if Window interprets Magic Spots Attr Attribute 1 for low through 5 for high or color attribute FLRCO Current FLRCO value Before Method to do before window is displayed After Method to do when window is done InpBefore Method to do before an input field is entered InpAfter Method to do after field entry is complete A window is a box on the screen where all output and input takes place. In DOS, the sides of the box are one character width wide and one character width tall. A shadow on the right side takes two character columns Chapter Five - JORF Functions 301 and on the bottom takes an additional character row. Under Microsoft windows, an overlapped window with wide borders is displayed using your default color scheme. An optional title may be displayed centered in the top line, and a message may be displayed in the bottom line left side. DOS Windows use direct video access unless you specify otherwise in the JORF.INI file. DOS windows have an exploding speed, which changes how the windows are displayed. All console input and output takes place on the top window displayed on the screen. There is no facility to update a window that is not the top window on the screen, even under MS-Windows. If Title is specified, it will be displayed centered on the top of the window. If the width of the title exceeds the window width specification then the window width will be increased to accommodate the title. Magic spots in the title will be interpreted. If Text is specified, the window is created exactly the size of the text to be displayed. If the text is greater than the screen length or width, the window will expand to the boundaries of the screen. Commonly the text attribute is passed as an indented section of the program. Any indented section is passed by the interpreter as the last parameter to the command preceding the indented section. Text is required if this window is to be edited using Line:Inp. If Row and Col are specified, the position of the window will be moved to the position indicated. If they are negative, then the window will be placed relative to the bottom right corner of the screen. If the window dimensions do not entirely fit on the screen, because Text is too large or Length too long or Width too wide the Row and Col values will be changed so that the window will entirely fit on the screen. The Len (Length) and Wid (Width) parameters can be used to set the exact size of the window. These parameters will override the size of Text. The Level parameter must specify the value of here in the method that creates the window. When that method is completed, the window will automatically be erased. The JORF Manual (Shareware Disk Version) 302 Setting Window Structure Elements When a window is created, a window structure is allocated that can be referenced using Win:Ptr. This structure may contain any or all of the elements referenced above. Some of these elements, like InpRow and InpCol are set by the interpreter to current values. You may set others to influence the way the window operates. Structure elements may be set in two ways. First, they may be set prior to calling Win:Add by creating a window structure and setting the elements normally. The second way is to set the element values directly in the input definition area of the text of the window. This syntax is the same as setting up buttons and other text on the window. CurRow and CurCol are set by the interpreter to the current row and column positions of the cursor during data entry. MouseRow and MouseCol are set to the position of the mouse at the time of the last button press or release. RowOff and ColOff are set to the row and column offset if the input in the window is shifted to the left or bottom. These values are only set during input, and only if the current field is shifted because the cursor is too far to the left or down. InpRow, InpCol, InpLen, and InpWid are set to the appropriate values for the current data entry field. Text is used to specify the text in the window, or to define data entry fields using a text definition. The interpreter does not change this value. Type actually changes the color mode for the window. You can set up new color sequences in the JORF.INI file, and then specify them here. That way, each type of window in your application has its own colors. Setting Magic to False will keep the window from trying to interpret magic spots (fields surrounded by {curly brackets}). Normally Magic is TRUE, and any bracket expression is interpreted. Setting Attr changes the starting attribute for text display in the window. Chapter Five - JORF Functions 303 Setting FLRCO changes the current wrap mode. The default mode is "L" for left justified text. Setting Before specifies a method to be executed before any data entry takes place on the window. It can be used to display additional information for the operator, or to test input or display parameters. If the Before method returns FALSE, the window entry is ignored. Setting Display is similar to setting Before. The difference is that the Before method executes before any part of the window is displayed, but the Display routine executes after the window box is showing. The Display routine can then add visual elements to the window that are not included in buttons and fields that make up the rest of the window definition. Setting After specifies a method to be executed when the operator attempts to exit the window using the Escape key or the window close button. On text entry windows, it is common to specify a method to ask whether to save the changed document before exiting the window. If the After method returns False, then the window remains displayed as if the operator did not request an exit. InpBefore and InpAfter may be used to specify methods that must be run before and after every input field (including buttons and check boxes) in the window. These methods are commonly used to lock the record, as well as qualify the operator rights to change the field. If the Before method returns False, the operator will not be able to change the field. If the After method returns False, the operator will not be able to move to another field (presumably until the operator corrects the field value.) Example This first example is just a little program to show row and column placement. Windows:Start Win:Add ("Big", 2, 2, -2, -2) Win:Add ("Top Right", 3, 3, 3, 15) Win:Add ("Bottom Right",-3, 3, 3, 15) Win:Add ("Bottom Left", -3, -3, 3, 15) Win:Add ("Top Left", 3, -3, 3, 15) Win:Add ("Tall", 3, 45, -4, 10) Win:Add ("Wide", 10, 3, 3, -4) Win:Pause Return Ok The JORF Manual (Shareware Disk Version) 304 This next function CENTERED.J uses a couple commands to set the window type and FLRCO mode. Centered:Start Win:Add (Null,0,0,7,30) Type:"Message" FLRCO:"Center" Button:"Ok" Row:5 Col:10 Wid:12 This text uses a FLRCO command to center the text, and a TYPE command to set the window type. Return(Ok) The main window in TUTORIAL.J contains menu items and text. The prompts and buttons are defined in the text section. (Sorry about the microscopic text, had trouble fitting these.) Tutorial:Start Event:Add("Tutorial") Jorf:File("TutText.J") Win:Add ("Josephine's Recipe Filer Tutorial", 0, 0, 23, 78, Here.) Menu:"&File" Menu:"E&xit Alt-X" Action:"Jorf:Exit" This tutorial is {prompt:"&Hypertext", Action:"Tutorial:Box('Intro:Hyper')"}. & Press {Bold:"Lo"}Enter{Bold:"No"} to see the highlighted subjects. & Use your arrow keys to highlight different subjects. You can & zoom to highlighted letters by holding the Alt key down & while pressing that letter. {Prompt:"&Josephine", Action:"Tutorial:Box('Intro:Jo')"}'s Recipe Filer, & JORF(tm), is a new computer & language. JORF was created by a & {Prompt:"&Grunt-Programmer" Action:"Tutorial:Box('Intro:Grunt')"} & frustrated by low level math based computer languages & that are inapproprate for business data processing. With the JORF & language you can easily create data entry screens, & and write sophisticated routines using an Object Oriented & data base manager. Press "Enter" now, to read more about the Hypertext system. & Then, highlight the various topics and explore & this Tutorial. Thank you for your support. {Group:"Hypertext Topics" Row:13 Col:4 Len:5 Wid:70} {Prompt:" &About the JORF Language " Row:14 Col:08 Wid:30 Action:"Tutorial:Box('Tut:About')"} {Prompt:" JORF &Programming Basics " Row:15 Col:08 Wid:30 Action:"Tutorial:Box('Tut:Basic')"} Chapter Five - JORF Functions 305 {Prompt:" JORF Ad&vanced Programming " Row:16 Col:08 Wid:30 Action:"Tutorial:Box('Tut:AdvStart')"} {Prompt:" &OOP Programming Concepts " Row:17 Col:08 Wid:30 Action:"Tutorial:Box('Tut:Oop')"} {Prompt:" JORF &Window Manager " Row:18 Col:08 Wid:30 Action:"Tutorial:Box('Tut:DataEntry')"} {Prompt:" G&etting Started with JORF " Row:14 Col:42 Wid:30 Action:"Tutorial:Box('Write:Start')"} {Prompt:" &Quick Demonstration " Row:15 Col:42 Wid:30 Action:"Tutorial:Box('Quick:Start')"} {Prompt:" &Registering JORF " Row:16 Col:42 Wid:30 Action:"Tutorial:Regist"} {Prompt:" JORF Company Produc&ts " Row:17 Col:42 Wid:30 Action:"Tutorial:Box('Tut:Prod')"} {Prompt:" &Contacting JORF Company " Row:18 Col:42 Wid:30 Action:"Tutorial:Box('Tut:JorfCo')"} {Button:"Run &Sample Prog" Row:20 Col:2 Wid:22 Action:"Tutorial:Samples"} {Button:"See &Debugger" Row:20 Col:28 Wid:22 Action:"Kbd:Put('Ctrl_Break_Key')"} {Button:"E&xit" Row:20 Col:56 Wid:22 Action:"Jorf:Exit"} Return (Ok) The last example is the screen from the MAILLIST.J sample program, that defines a complex window using fields, buttons and boxes. MailList:Start | Little Mail List Program New (Contact:Con) | Create Contact Structure Jorf:File ("CONTACT.JCM",Here) | Set Database File to CONTACT.JCM Event:Add ("MailKey","Key",Here) | Set MailKey as a keystroke handler Mem:Ptr->IndexName = "FullName" | Index Name | The main screen with menu options Win:Add ("Josephine's Mail List Manager", 2, 2, 22, 78, Here) Menu:"&File" Menu:"&About " Action:"MailList:About" Menu: Menu:"&Rebuild ", Action:"Jorf:Rebuild" Menu: Menu:"E&xit Alt-X", Action:"MailKey:Esc_Key" Menu:"&Edit" Menu:"&Add Alt-A", Action:"MailList:Add(Con)" HotKey:"Alt_A_Key" Menu:"&Change Alt-C", Action:"MailList:Change(Con)" Menu:"&Delete Alt-D", Action:"MailList:Delete(Con)" HotKey:"Alt_D_Key" Menu:"&Search", Menu:"&Name ", Action:"MailList:KeySearch (Con, 'FullName' ) Menu:"&Company ", Action:"MailList:KeySearch (Con, 'Company' ) Menu:"&Last Name ", Action:"MailList:KeySearch (Con, 'LastName' ) Menu:"&Phone ", Action:"MailList:KeySearch (Con, 'WorkPhone') The JORF Manual (Shareware Disk Version) 306 Menu:"&Zip ", Action:"MailList:KeySearch (Con, 'ZipCode' ) Menu:"&Reports" Menu:"&Mail List ", Action:"MailList:List()" Menu:"&This Contact ", Action:"MailList:PrintData(Con)" Menu:"&Lotsa Labels ", Action:"MailList:ContinLabels(Con,'All')" Menu:"&One Label", Action:"MailList:ContinLabels(Con,'One')" InpBefore:"MailList:Lock(Con)" Group:"&Browse List", Row:1 Col:41, Len:6, Wid:36 List:"" Field:"Con" Next:"MailList:NextRecord(Con,'Next')" Prev:"MailList:NextRecord(Con,'Prev')" Show:"MailList:Show(Con)" Before:"MailList:Write()" Display:"(Mem:Ptr->Locked==Null)" Group:"&Contact Name and Address", Row:1, Col:1, Wid:38, Len:6 Input:"Name ", Wid:30, Field:"Con->FullName" After:"MailList:SplitName(Con)" Input:"Company", Wid:30, Field:"Con->Company" Input:"Address", Wid:30, Field:"Con->Addr1" Input:" ", Wid:30, Field:"Con->Addr2" Input:" ", Wid:30, Field:"Con->Addr3" After:"MailList:ZipCode(Con)" Group:"Mail List Fields" Row:9 Col:1 Len:11 Wid:76 Input:"&Work Phone" Field:"Con->WorkPhone" Row:10 Col:2 Wid:20 Input:"&Home Phone" Field:"Con->Homephone" Row:11 Col:2 Wid:20 Input:"Fax &Phone " Field:"Con->FaxPhone" Row:12 Col:2 Wid:20 Input:"Birthda&y " Field:"Con->BirthDay" Row:13 Col:2 Wid:20 Input:"C&omment " Field:"Con->Comment" Row:15 Col:2 Wid:50 Input:"&Last Name " Field:"Con->LastName" Row:10 Col:35 Wid:14 Input:"Dear " Field:"Con->Dear" Row:11 Col:35 Wid:14 Input:"Zip Code " Field:"Con->Zipcode" Row:12 Col:35 Wid:14 Radio:"Fr&iend" Check:"Con->Type=='Friend'" Action:"Con->Type='Friend'" UnAction:"Con->Type= Null" Row:10 Col:62 Radio:"Fa&mily" Check:"Con->Type=='Family'" Chapter Five - JORF Functions 307 Action:"Con->Type='Family'" UnAction:"Con->Type= Null" Row:11 Col:62 Radio:"Clien&t" Check:"Con->Type=='Client'" Action:"Con->Type='Client'" UnAction:"Con->Type= Null" Row:12 Col:62 Radio:"&Vendor" Check:"Con->Type=='Vendor'" Action:"Con->Type='Vendor'" UnAction:"Con->Type= Null" Row:13 Col:62 HLine:"&Notes" Row:16 Col:2 Len:1 Wid:76 Text:"" Field:"Con->Notes" Row:17 Col:2 Len:4 Wid:76 Return (Ok) | That is all, Folks! The JORF Manual (Shareware Disk Version) 308 Win:Attr Function Win:Attr ( Attribute ) Purpose Sets attribute for text in a window. Returns None. Notes Whenever anyone in the IBM PC world says Attribute, you know they are talking about colors on the monitor. This command sets the colors for text to be displayed. The attribute may be "Hi" for highlighted text, "Low" for low highlight. You can also set one of five values for attribute, 1 corresponds to normal, through 5 for high. Number INI Name What it is used for 1 Normal Normal text and field display 2 Low Highlighted letters in field/menu display 3 Medium Box and Graphic lines 4 High Fields not selected, selected menu item 5 Bold Selected fields, Selected Menu item letter Version 2.1 introduces the ability to set any color using attribute numbers. Colors on a PC are expressed using a background and foreground color. The background is the base screen color, and the foreground will be the color of the letters on the background. When expressed in this way, you can use the IBM attribute numbers or you can use JORF names for those colors. Chapter Five - JORF Functions 309 JORF Color Name Number Black 0 Blue 1 Green 2 Cyan 3 Red 4 Magenta 5 Brown 6 White 7 (Actually light gray) Gray 8 (Actually dark gray) Light Blue 9 Light Green 10 Light Cyan 11 Light Red 12 Light Magenta 13 Yellow 14 Bright White 15 (Actually white) When setting attributes, the colors are expressed as a pair separated by a slash. The first color represents the foreground, and the second is the background colors. The following two commands are equivalent and will change the color to use white text on a blue background: Win:Attr("Bright White/Blue") Win:Attr("15/1") You can set attribute without using this command by setting Win:Ptr->Attr = Attribute. Win:Ptr->Attr="Bright White/Blue" Example The Colors.J sample program shows all possible colors. Colors:Start New(I) Win:Add ("Color Demonstration", 0, 0, 16, (16*4), Here) For (i=0 thru 255) Win:Attr((i%16)+"/"+Num:Int(i/16)) Str:Put(To:Str(i," ###")) If ((I%16)==15) Str:PutLine() Win:Pause Return (Ok) The JORF Manual (Shareware Disk Version) 310 Win:Block Function Win:Block ( Function, Command ) Purpose Do some WordStar style block commands. Returns None. Notes JORF Version 2.0 introduces the same Block Move and Copy commands found in other Wordstar style editors. You can access these functions using Win:Block. Win:Block ("Mark", Marker). Places a block marker. Marker can be a number from 0 through 9, "Beginning" or "End". Win:Block ("Goto", Marker). Move cursor to a block marker. Marker can be a number from 0 through 9, "Beginning" or "End". Win:Block ("Copy"). Copies a marked block to current cursor location. Nothing is copied if block is not correctly marked, or if cursor is within the block. Win:Block ("Delete", Marker). Delete the marked block, no matter where the cursor is located. Win:Block ("Move"). Moves a marked block by copying it to the current cursor location and then deleting it from its prior location. Win:Block ("Read", FileName). Reads a block from disk into the current cursor location. File is assumed to be a text file. This read adds lines one by one, and is much slower than File:Load. Win:Block ("Write" FileName). Writes a marked block to disk. Does not change block markers. Chapter Five - JORF Functions 311 Win:Chg Function Win:Chg ( Marker, NewFields ) Win:Chg ( Marker, Row, Col, Len, Wid, NewFields ) Purpose Change the fields in a window for something new. Returns None. Notes This command will make your windows sing. Use it to redraw sections of a window based on data entry by the operator. This function dynamically reallocates and re-displays a portion of a window. The key to using this command is to use Marker commands in your definition. When a group of fields is preceded by a marker, they can be changed simply by referencing that marker. Each marker section of fields goes until the next marker. Markers cannot be nested. If you call this command with Row, Col, Len and Wid, then the section of the screen is physically erased and redrawn. This is the common way to display window changes. If the changes are so minor that the screen does not need to be redrawn, then you can use the short form of this function. Example See Contact.J. The JORF Manual (Shareware Disk Version) 312 Win:Del Function Win:Del Purpose Delete top window on screen. Returns None. See Also Win:Add. Notes Deletes a single window on the screen. This command is not generally used because windows are deleted automatically when the method that creates them is complete. Example See Arr:Len. Chapter Five - JORF Functions 313 Win:Dsp Function Win:Dsp Purpose Signal a redisplay of all windows. Returns None. See Also Win:Add. Notes Signals to the interpreter that all data entry windows should be redisplayed, presumably because data displayed in the window may have changed. During data entry, changes to the current field are made by the operator. Other fields, however, may have values that have changed because of the entry. Win:Dsp forces all fields to be redisplayed, so that any changed values will be shown. Changes on one window may affect the display of a prior window. For this reason Win:Dsp sends the signal to all windows. Windows are redisplayed during the "Idle" cycle. This happens about one second after the system begins to wait for data entry from the operator. If the operator has typed ahead, then the system does not go Idle and the redisplay process waits until the current task is complete. Example See MAILLIST.J. The JORF Manual (Shareware Disk Version) 314 Win:FLRCO Function Win:FLRCO ( Mode ) Purpose Change wrap mode for text on the window. Returns Previous wrap mode as a string containing a single lower case letter "f", "l", "r", "c" or "o". See Also Win:Add. Notes Sets the current window mode for text justification. The name of this command comes from the possible Modes; "Full", "Left", "Right", "Center", or "Off". "Off" turns off the text wrapping feature so text that overflows the window boundary will not be displayed. The other modes all turn on the wrapping feature that wraps text at the nearest word boundary. You can set FLRCO without using this command by setting Win:Ptr->FLRCO = "F" (or "L" or "R" or "C" or "O". This is now the preferred method for setting FLRCO, and the command may be eliminated in later versions of JORF. Example The CENTERED.J file uses a FLRCO command to set the justification mode to "Centered". Centered:Start Win:Add (Null,0,0,7,30) Type:"Message" FLRCO:"Center" Button:"Ok" Row:5 Col:10 Wid:12 This text uses a FLRCO command to center the text, and a TYPE command to set the window type. Return(Ok) Chapter Five - JORF Functions 315 Win:Magic Function Win:Magic ( Mode ) Purpose Change whether curly brackets are interpreted in text on the window. Returns Previous Magic mode True or False. See Also Win:Add. Notes Sets the mode for "Magic", whether {curly bracket} expressions are interpreted in text display. Usually this mode is True, allowing all variable values and input expressions to be interpreted. However, when editing commands or program text, you want this mode off so the that curly brackets are not interpreted. You also want to set FLRCO "Off" to editing program text. Otherwise text lines will wrap at the window borders. Astute programmers may note that variables in windows are replaced, even when they are not in the current method. The "Magic" system looks down the entire stack for a named variable, and is not limited by the current method which may just display the window. You can set Magic without using this command by setting Win:Ptr->Magic = True (or False). This is now the preferred method for setting Magic, and the command may be eliminated in later versions of JORF. The JORF Manual (Shareware Disk Version) 316 Win:Msg Function Win:Msg ( Message ) Purpose Display a message in the Window. Returns None. See Also Win:Add. Notes Displays a message in the last line of the current window. If the message is absent or null then the current message is deleted. This command acts slightly differently under MS-DOS and MS-Windows. Under DOS, the message is placed in the bottom border of the window. Under Windows, it didn't look good, so as an alternative Win:Msg expands the window by one line and displays the message on the new line of the window. Example CharEx:Start New (Count, Str1, Str2) Str1="This Text will Disappear" Str2="This Text will Appear" Win:Add ("Char Example", 10, 25, 2, 30, Here) Str:Put (Str1) | Show Str1 Win:Msg ("Press Enter to continue...") Win:Pause | And pause for Effect Win:Msg | Count = Str:Len (Str1) | Set Counter While (Count > 0) | While GT Zero Move:To (1,1) | First line Char:Del (1) | Take 1 Away Move:To (2,1) | Second line Char:Ins (1) | Add one, Add char Char:Put (To:Ascii (Str:At (Str2, Count, 1))) --Count | Decrement Count Win:Pause(5) | Pause 5/100 seconds Win:Msg("Press Enter to continue...") Win:Pause | Done! Return | Bye Chapter Five - JORF Functions 317 Win:Pause Function Win:Pause ( Hundredths ) Purpose Pause. Returns The Key that was hit, if one was hit, to end the pause. See Also Kbd:Get. Notes Pauses for the specified number of Hundredths of seconds. Due to the quirky hardware engineering of an IBM PC, exact Hundredths are a basic unit, but cannot be obtained by a program. Generally, the finest resolution is about three hundredths of a second at a time. Anyway, this command will pause as close as it can get to the hundredths you specified. If the operator hits any key, the pause will end. If Hundredths is zero, the pause will continue indefinitely. If the pause is greater than 5 seconds, a "Happy Goat" will be displayed. Example This example is the much reviled SayLineByCharacter method that is used in the tutorial for program scripts. Script:SayLineByCharacter (j) New (I, C) | Create new vars I and C I=1 | Start with 1 While (Ok) C=Str:At(J, I, 1) | Get Character If (C==Null) | Done? Break Str:Put (C) | Put it ++I | Next Character Win:Pause (1) | Pause a hundredth Str:PutLine() | Carriage Return (Putting null line) The JORF Manual (Shareware Disk Version) 318 Win:Ptr Function Win:Ptr Purpose Get the Structure that was used to create the window. Returns A pointer to the Structure that was used to create the window. See Also Win:Add. Notes It is common to need information about the current window from within methods that check and display information for the window. The most important vehicle for this information is this function. By using Win:Ptr you have access to more than a dozen fields including row, column, length and width of the window, row, column, length and width of the current edit field, mouse position and status, current attribute and the value of the current input. Win:Ptr->Row, Win:Ptr->Column, Win:Ptr->Len and Win:Ptr->Wid reflect the actual window, and may have changed if the window was adjusted to fit on the screen. (This is one way to see if the user is in EGA/VGA 43/50 line mode by creating a window with a length of -1 and then testing Win:Ptr->Len to get the actual last line of the screen). If you are editing a field or text, Win:Ptr->CurRow and Win:Ptr->CurCol will be set to the cursor row and column. Win:Ptr->CurLine will be set to the current input value. If the mouse pointer is inside the window Win:Ptr->MouseRow and Win:Ptr->MouseCol are set to current mouse position. If the current input field is more than one line (a text input), Magic is False, and FLRCO is "Off", then the window can move right or down to accommodate text that is larger than the window. In this case Win:Ptr->RowOff and Win:Ptr->ColOff reflect the relative position of the top left corner of the text in the window. You can test and set Win:Ptr->FLRCO, Win:Ptr->Magic and Win:Ptr->Attr. When these values are assigned, the interpreter automatically calls the appropriate function. Chapter Five - JORF Functions 319 Win:Repl Function Win:Repl ( SearchString, ReplaceString, Flags ) Purpose Do some WordStar style string replacing commands. Returns None. See Also Win:Search. Notes The JORF Window Manager uses the same Search and Replace commands found in other WordStar style editors. You can access these functions using Win:Search and Win:Repl. Flag values are: B Search backward to top - Normally searches forwards. G Global replace - Normally replaces just one. N Do not prompt - Normally prompts for each replace. U Case insensitive search - Normally is case sensitive. W Search for Whole Words - Normally allows partial words. A numeric value with the flags is considered the number of items to skip before stopping. For instance, GU2 will search globally, without case sensitivity, and will replace two instances of the item. This command can only be used within an edit window, and will do nothing if used on a text that is not currently being edited in the window. The JORF Manual (Shareware Disk Version) 320 Win:Search Function Win:Search ( SearchString, Flags ) Purpose Do some WordStar style string search. Returns None. See Also Win:Repl. Notes The JORF Window Manager uses introduces the same Search and Replace commands found in other Wordstar style editors. You can access these functions using Win:Search and Win:Repl. Flag values are: B Search backward to top - Normally searches forwards. U Case insensitive search - Normally is case sensitive. W Search for Whole Words - Normally allows partial words. A numeric value with the flags is considered the number of items to skip before stopping. For instance, GU2 will search globally, without case sensitivity, and will stop on the second instance of the search item. This command can only be used within an edit window, and will do nothing if used on a text that is not currently being edited in the window. Chapter Five - JORF Functions 321 Word:At Function Word:At ( Structure, Position ) Purpose Returns a word in parsed command line, or value of a member of a structure. Returns Word. See Also Word:AtPut, Class:At. Notes Both structures and text lines are stored as an array of Class:Word pairs. The number of words can be obtained using Word:Len. Arrays Array elements are normally accessed using square brackets []. But if you find reason, you can use Word:At to get the element. Word:Len-1 will be the number of elements used in the array. Structures Normally, structure elements are accessed using pointers. However, they may also be accessed by referencing the elements directly using this command. This has to be done to examine the stack, because it is not a normal class. Text Text lines may be examined to obtain the class and values of items on that line. The line is automatically parsed when Word:At is used. Unlike the parse used by the interpreter, the Word:At parse separates all punctuation characters into individual words, even if they are two character symbols like the pointer->operator. Example See Event:Add. The JORF Manual (Shareware Disk Version) 322 Word:AtDel Function Word:AtDel ( Structure, Position, Count ) Purpose Squeezes a structure. Returns None. See Also Word:At, Word:AtIns, Str:AtDel. Notes Squeezes elements out of the center of a structure. Unlike Word:At, Word:AtDel and Word:AtIns delete and insert the Class/Word pair, so there is no need for the equivalent Class:AtDel and Class:AtIns functions. If the Count argument is missing then all elements of the structure starting at Position are deleted. Arrays This function cannot be used on arrays. Structures Deleting "Word" values will eliminate structure elements. Care should be taken not to delete more than you intend. Each structure may have elements in a different order, even when the structures are from the same class. That is because elements are kept in the order assigned, and assignment may be arbitrary. You should never delete the first element of a structure, because this affects the class of the structure. Text This function has no effect on lines of text. Chapter Five - JORF Functions 323 Word:AtIns Function Word:AtIns ( Structure, Position, Count ) Purpose Expands a structure. Returns None. See Also Word:At, Word:AtDel, Str:AtIns. Notes Inserts elements out of the center of a structure. Unlike Word:At, Word:AtDel and Word:AtIns delete and insert the Class/Word pair, so there is no need for the equivalent Class:AtDel and Class:AtIns functions. If the Count argument is missing then the structure remains unchanged. Arrays This function cannot be used on arrays. Structures After inserting, you must use Class:AtPut and Word:AtPut to set the Class/Word values. Care should be taken not to insert at position 1, because the first pair contains the class name for the structure. Text This command has no effect on lines of text. The JORF Manual (Shareware Disk Version) 324 Word:AtPut Function Word:AtPut ( Structure, Position, Value ) Purpose Changes the value in a member of a structure. Returns None. See Also Word:At, Class:AtPut. Notes Both structures and text lines are stored as an array of Class:Word pairs. You can use this function to change the "Word" portion of such a structure. The number of words in a structure or line can be obtained using Word:Len. Arrays This function cannot be used on arrays. Structures Replacing a "Word" value will not change the length of the structure. You should not replace the first word of the structure, unless you are intentionally changing the class of the structure. To change the class of a structure, you must replace the first "Class/Word" pair of the structure with a Null "Word" and a class indicating the new class name. Text When a word is replaced in a text line, the Str:Len of the line is changed by the difference in lengths between the old and new values. Chapter Five - JORF Functions 325 Word:In Function Word:In ( Structure, Word ) Purpose Searches for the existence of Word in a structure or parsed command line, and returns the position if it is found. Returns zero if Class is not found. Returns Position of Word or zero if not found. See Also Str:In, Word:At, Class:In. Notes Both structures and text lines are stored as an array of Class:Word pairs. You can use this function to search for the "Word" portion of the pair. When searching for a "Word" the value being searched for need may be a string, number, text pointer or array. The number of words can be obtained using Word:Len. Word:In can be used to get the value of an element in a structure without using the structure pointer operator. Arrays You can use Word:In to find the position of an array value without regard to position. Structures You can use Word:in to find the absolute position of a value in a structure without regard to the structure element name. The JORF Manual (Shareware Disk Version) 326 Text There are two ways to search for a word in a line of text. One is to use Str:In to find a substring, and the other is to use Word:In to find a parsed word. The words are parsed using space or punctuation character delimiters. Expressions quoted with single or double quotes are considered a single word. Str:In("Four score and twenty","And") 12 Word:In("Four scord and twenty", "And") 3 Str:In("Josephine's Pen", "Pen") 13 Word:In("Josephine's Pen", "Pen") 4 Chapter Five - JORF Functions 327 Word:Len Function Word:Len ( Structure ) Purpose Returns the number of elements in a structure, or the number of words in a parsed text line. Returns Number of words. See Also Word:At, Str:Len. Notes Returns the number of words in a line of text, and the number of elements in a structure or array. This function is commonly used with Word:At to examine text, and structure on an element by element basis. Arrays Returns exactly the same value as Arr:Len(). This function is a little more general, and is the preferred function if you are counting expressions in a variable that may or may not be an array. Setting an array element to null is the same as "using" it, so if you set A[2000]=null, then the array length will be 2000. Structures The length of a structure includes a structure header element that contains the class name and a pointer to the class definition. So a structure with three elements has a Word:Len of four. Structures do not have the same number of elements as the class definition. Even if there are 20 elements in a class definition, a structure will only store those elements that have a value. Elements that have not been set are reported as Null, but in fact they are not stored at all. Elements are not moved when set to null, except when the file is rebuilt. So setting a structure element to null will not shrink an array, but the array will shrink if stored in a file that is then rebuilt. Text The origin of this function lies in the origin of JORF as a Japanese/English language translator. When I was trying to build one in late 1987 I got so frustrated by the memory and file management problems of the C language that I decided to create a new language to do The JORF Manual (Shareware Disk Version) 328 my parsing and dictionary management. My new language became the core of the JORF language. In it's parser role, the Word:Len() function considers each word separate, as well as each punctuation character. Single and double quotes are handled specially. Quoted expressions are considered a single word. The following lines are shown with their lengths: Line Word:Len This is a line of text 6 A line with (Parentheses) 6 "A Quote" 1 Another 'Quote with a period'. 3 !@#$%^&*() 10 "!@#$%^&*()" 1 '"' 1 Chapter Five - JORF Functions 329 Appendix A JORF Language Reference Basic Rules Indentation controls program flow. Commands and variable names are not case sensitive. The end of line is the end of the line. The comment character is a pipe symbol (|). Parameter lists are surrounded by Parentheses Key Words Class Used to declare a new class. Parent In a class definition, designates a parent class. Jorf The default class for all objects. Index Declares an index field within a class Poly Indicates a polymorphic method call Math Symbols and Order of Operations -> Structure Element Pointer [] Array reference - ++ -- Negation, Increment, Decrement * / % Multiplication, Division, Modulus + - Addition and Subtraction = <> != Equality and Inequality > < >= <= Comparison && ?? And Or Logical And, Or = Assignment of value The JORF Manual (Shareware Disk Version) 330 Appendix B Library Functions Function Description Returns Arr:Del (Arr,Pos,Cnt) Delete Cnt Elements at Pos Array Arr:Dir (WildCard,Excl,Wid) Directory minus exclusions Array Arr:Ins (Arr,Pos,Cnt) Insert Cnt Elements at Pos Array Arr:Len (Arr) Number of Elements Count Arr:Pick (Arr,Cmd,T,R,C,L,Df) Show a Pick Menu Pick Arr:Printers Returns Printer List Array Arr:Sort (Arr,Cmd,Dir) Sort Ascending/Descending Array Char:Del (Count) Del Spaces None Char:Get Get ASCII value Value Char:Ins (Count) Ins Spaces None Char:Put (Value) ASCII value to Screen None Char:Print (Printer, Value) ASCII value to Printer None Class:At (Struct,Pos) Class at Position Class Class:AtPut (Struct,Pos,Class) Change Class If put Class:In (Struct,Class) Get Position Position Class:Read (Name) Read Class If Read Class:Write Write current Class If Written Date:Add (Date,Days,Mths,Yrs) Add Days, Months, Years to dateNew Date Date:Get Get today's date Today's date Date:Set (Date) Set system clock Ok if set Date:SetFmt (FormatStructure) Set default format, Month names None Date:Str (Date, Format) Convert date to string date Date string Date:Sub (Date,Days,Mths,Yrs) Subtract Days, Months, Years from date New Date Db:Append (Name,Line) Append record to file If Ok Db:Close (Name) Close a dBASE file If Ok Db:Create (Name) Create a dBASE file If Ok Db:Delete (Name,Recno) Delete a Record Ok if deleted Db:Go (Name,Recno) Go Top, Bottom or Recno Recno if Ok Db:Info (Name,InfoFlag) Get file size,found,deleted Info result Db:Lock (Name,Recno) Lock and read Record Record if Locked Db:Map (Nm,Lev,Class,Map) Map dBASE File None Db:Ntxord (Name,Ntxnumber) Set index to use Ok if valid index Db:Pack (Name,Showit) Rebuild dBASE file, NTXs If Ok Appendix 331 Function Description Returns Db:Read (Name,Recno) Read Line/Record Record Db:Recall (Name,Recno) Undelete a Record Ok if was deleted Db:Seek (Name,Indexval) Seek for an index key Recno if found Db:Set (Name,Flag,Value) Set dBASE settings Old set value Db:Skip (Name,Recno,Skipby) Get next/Prev record number Recno if not Eof Db:Unlock (Name,Record) Unlocked a locked record If Ok and was locked Db:Write (Name,Record) Write dBASE Record None Event:Add (Class,Type,Lev) Add Event Class None Event:Del (Type) Delete Event Class None Event:Do (Method,Type) Do Event Method Return False Logical False Null File:Append (Name,Line) Append line or record to file If Ok File:Backup (Name) Create a Backup If Ok File:Chgdir (Path) Change Directory If Ok File:Close (Name) Close a file If Ok File:Copy (From,To) Copy File If Ok File:Create (Name) Create a mapped or dBASE file If Ok File:Del (Name) Delete File If Ok File:Exist (Name,Access) Check Existence/Access If Ok File:Len (Name) Get Size of File Size in K File:Load (Name) Load Text File Text File:Lock (Name) Lock a file for exclusive use If Locked File:Map (Nm,Lev,Class,Type,Map) Map ASCII or dBASE File None File:MoveTo (Name,Pos) Move to Beg/Ene If Ok File:Ok (Name) Not EOF in File:Read If Ok File:Print (Name,Device,Flags) Print file to print device If Ok File:Read (Name,Size,Off) Read Line/Record Line/Record File:Rename (From,To) Rename File If Ok File:Save (Name,Text) Save Text to File If Ok File:Unlock (Name) Unlocked a locked file If Ok and was locked File:Write (Name,Line,Size,Off) Write Line/Record None For/Thru/Step Incrementing Loop None Here Return level Level If/Else Conditional Branch None Jorf:Cls Clear DOS Screen None Jorf:Del (Variable) Delete Text None Jorf:Do (MethodName) Interpret a string Return Jorf:Dup (Text) Copy Text or Struct A Copy Jorf:Exit (Status,Msg,Cmd) Exit Doesn't Jorf:File (Name Level) Current Project None Jorf:Flush (Minimum) Flush memory None Jorf:Info (InfoFlag) Get disk space, Memory, Etc. Info value The JORF Manual (Shareware Disk Version) 332 Function Description Returns Jorf:Ini Reread .INI file None Jorf:Move (Srce,Dest,Class) Move Buffer A Copy Jorf:Pack Pack JORF File None Jorf:Printer Display printer selection menu Device selected Jorf:Rebuild Rebuild JORF File None Jorf:Sound (Freq,Dur) Make a Sound None Jorf:System (Cmd,Flgs,Msg) DOS shell Return Jorf:Write (Variable) Write var to current project If written Kbd:Bye Flush Keyboard Stream None Kbd:Get (CursorSize) Keyboard Input Key Kbd:Got Last Key Value Key Kbd:Hit Key Waiting? True/False Kbd:Put (Keys) Stuff Keystrokes None Key:Add (RuleStructure) Add String Key None Key:Del (RuleStructure) Delete String Key Sets Found Key:Find (RuleStructure) Find String Key Sets Found Key:Next (RuleStructure) Find Next Sets Found Key:Prev (RuleStructure) Find Prev Sets Found Line:Del (Count) Delete Lines None Line:Inp (Fld,R,C,L,W) Input Field/Text Field/Text Line:Ins (Count) Insert Lines None Line:Out (Fld,R,C,L,W) Output Field/Text None Line:Rel Release current input None Mem:Ptr A Global Pointer None Move:To (Row,Column) Move Cursor None Move:By (Row,Column) Move Cursor None Msg:Add (Title,Type,Text) A Dialog Box True/False New (Class:Var1,Class:Var2) Create Variables None Null Nothing Null Num:Abs (Num) Absolute value Number Num:Btw (A,B,C) A, Between B and C Number Num:Exp (Num) Exponent e to the Num Number Num:Log (Num) Log of Num Number Num:Max (A,B) Higher of A or B Number Num:Min (A,B) Lower of A or B Number Num:Pow (Num,Pow) Num to the Power Number Num:Rand (High,Low) Random Number Number Num:Sqrt (Num) Random Number Number Ok Ok 1 Appendix 333 Function Description Returns Rep:Add (Title,R,C,L,W,Lev,Fmt) Create report file None Return (Value) Return a value None Rule:Add (RuleStructure) Add Rule None Rule:Del (RuleStructure) Delete Rule Sets Found Rule:Find (RuleStructure) Find Rule Sets Found Rule:Next (RuleStructure) Find Next Rule Sets Found Rule:Prev (RuleStructure) Find Previous Rule Sets Found Str:Aft (String,Chars) String after chars Substring Str:At (String,Pos,Len) Get Substring Substring Str:AtChar (String,Chars) String up to chars Substring Str:AtCut (String,Pos) Truncate String String Str:AtDel (String,Pos,Cnt) Delete Characters String Str:AtPut (String,Pos,Ins) Insert Characters String Str:AtSet (String,Pos,Ins,Cnt) Insert Rep Chars String Str:In (String,Substring) Get Substring Position Str:Ind (String) Num of lead Spaces Count Str:Len (String) Number of Chars Length Str:NPad (String,Length) Null pad string to Length Padded string Str:Pad (String,Length) Space pad string to LengthPadded string Str:Print (Prn,String) String to Printer None Str:Put (String) Display Text None Str:PutLine (Line) Display Text, NL None Str:RPad (String,Length) Space pad string Right Justified Padded string Struct:Find (Class,Index,Value) Find record w/ auto index Record Struct:Find (Class,Index,Value) Find record w/ auto index Record Struct:Find (Class,Index,Value) Find record w/ auto index Record Switch/Case/Else Conditional Branch None Text:Add (Line,Text) Create text block New Text Text:At (Text,Pos) Text Line at Pos Line Text:Bot (Text) Last Line of Text Last Line Text:Chg (Text,Line) Change line of text Text Text:Len (Text) Number of lines Line Count Text:Next (Text) Next line of Text Next Line Text:Pos (Text) Line num of Text Number Text:Prev (Text) Prev line of Text Prev Line Text:Ptr (Text) Ptr to indented Text Text Text:Top (Text) First Line of Text First Line Text:Wid (Text) Width of widest Line Width Time:Add (Time,Mins,Hrs,Secs) Add Minutes, hours, seconds New time Time:Get Get current time Now Time:Set (Time) Set system clock Ok if set Time:SetFmt (FormatStructure) Set default format, AM/PM name None The JORF Manual (Shareware Disk Version) 334 Function Description Returns Time:Str (Time, Format) Convert time to string time Time string Time:Sub (Time,Mins,Hrs,Secs) Subtract Minutes, hours seconds New time Time:Ticks Get Ticks Ticks To:ASCII (String) Get ASCII Value Value To:Caps (String) Cvt to Capitals String To:Char (Number) Cvt to Letter String To:Date (String) Cvt to Date Date To:Int (Number) Cvt to Integer Integer To:Lcs (String) Cvt to Lower Case String To:Num (String,Base) Cvt to Number Number To:Str (Number,Fmt,Base,Wid) Cvt to String String To:Time (String) Cvt to Time Time To:Ucs (String) Cvt to Upper Case String True Logical True 1 While/Break/Continue A Loop None Win:Add (Title,R,C,L,W,Lv,Txt) Add new Window None Win:Add (WindowStruct) Add new Window None Win:Attr (Attribute) Change Attribute None Win:Block (Cmd,Fnc) Do Block Function Null Win:Chg (Marker,R,C,L,W,Txt) Change button area in Window None Win:Del Delete Window None Win:Dsp Redisplay all Windows None Win:FLRCO (Mode) Change Wrap Mode Prev Mode Win:Magic (Mode) Change Interpret Mode Last Mode Win:Msg (Message) Set Message None Win:Pause (Hundredths) Pause Key Win:Ptr Get WindowStruct Structure Win:Repl (From,To,Flags) Replace Strings None Win:Search (Word,Flags) Replace Strings None Word:At (Struct,Pos) Word at Pos Word Word:AtDel (Struct,Pos,Cnt) Squeeze Structure None Word:AtIns (Struct,Pos,Cnt) Expand Structure None Word:AtPut (Struct,Pos,Word) Change Word at Pos None Word:In (Struct,Word) Get Position of Word Position Word:Len (Struct) Number of Words Count Appendix 335 Appendix C Keyboard Values Char Normal Shift Ctrl Alt a a_Key A_Key Ctrl_A_Key Alt_A_Key b b_Key B_Key Ctrl_B_Key Alt_B_Key c c_Key C_Key Ctrl_C_Key Alt_C_Key d d_Key D_Key Ctrl_D_Key Alt_D_Key e e_Key E_Key Ctrl_E_Key Alt_E_Key f f_Key F_Key Ctrl_F_Key Alt_F_Key g g_Key G_Key Ctrl_G_Key Alt_G_Key h h_Key H_Key BackSpace_Key Alt_H_Key i i_Key I_Key Tab_Key Alt_I_Key j j_Key J_Key Ctrl_Return_Key Alt_J_Key k k_Key K_Key Ctrl_K_Key Alt_K_Key l l_Key L_Key Ctrl_L_Key Alt_L_Key m m_Key M_Key Return_Key Alt_M_Key n n_Key N_Key Ctrl_N_Key Alt_N_Key o o_Key O_Key Ctrl_O_Key Alt_O_Key p p_Key P_Key Ctrl_P_Key Alt_P_Key q q_Key Q_Key Ctrl_Q_Key Alt_Q_Key r r_Key R_Key Ctrl_R_Key Alt_R_Key s s_Key S_Key Ctrl_S_Key Alt_S_Key t t_Key T_Key Ctrl_T_Key Alt_T_Key u u_Key U_Key Ctrl_U_Key Alt_U_Key v v_Key V_Key Ctrl_V_Key Alt_V_Key w w_Key W_Key Ctrl_W_Key Alt_W_Key x x_Key X_Key Ctrl_X_Key Alt_X_Key y y_Key Y_Key Ctrl_Y_Key Alt_Y_Key z z_Key Z_Key Ctrl_Z_Key Alt_Z_Key 0 0_Key Alt_0_Key 1 1_Key Alt_1_Key 2 2_Key Alt_2_Key 3 3_Key Alt_3_Key 4 4_Key Alt_4_Key 5 5_Key Alt_5_Key 6 6_Key Alt_6_Key 7 7_Key Alt_7_Key 8 8_Key Alt_8_Key 9 9_Key Alt_9_Key The JORF Manual (Shareware Disk Version) 336 Char Normal Shift Ctrl Alt F1 F1_Key Shift-F1_Key Ctrl_F1_Key Alt_F1_Key F2 F2_Key Shift-F2_Key Ctrl_F2_Key Alt_F2_Key F3 F3_Key Shift-F3_Key Ctrl_F3_Key Alt_F3_Key F4 F4_Key Shift-F4_Key Ctrl_F4_Key Alt_F4_Key F5 F5_Key Shift-F5_Key Ctrl_F5_Key Alt_F5_Key F6 F6_Key Shift-F6_Key Ctrl_F6_Key Alt_F6_Key F7 F7_Key Shift-F7_Key Ctrl_F7_Key Alt_F7_Key F8 F8_Key Shift-F8_Key Ctrl_F8_Key Alt_F8_Key F9 F9_Key Shift-F9_Key Ctrl_F9_Key Alt_F9_Key F10 F10_Key Shift-F10_Key Ctrl_F10_KeyAlt_F10_Key F11 F11_Key Shift-F11_Key Ctrl_F11_KeyAlt_F11_Key F12 F12_Key Shift-F12_Key Ctrl_F12_KeyAlt_F12_Key Space Space_Bar ! !_Key " "_Key # #_Key $ $_Key % %_Key & &_Key ' '_Key ( (_Key ) )_Key * *_Key + +_Key Alt_+_Key ,(comma) ,_Key -(minus) -_Key Alt_-_Key .(period) ._Key / /_Key :(colon) :_Key ;(semi-colon) ;_Key < <_Key = =_Key > >_Key ? ?_Key @ @_Key Alt_@_Key [ [_Key Escape_Key \ \_Key Ctrl_\_Key ] ]_Key Ctrl_]_Key ^ (carat) ^_Key Ctrl_^_Key _ __Key Ctrl___Key ` `_Key { {_Key | (pipe) |_Key } }_Key ~ (tilde) ~_Key Appendix 337 Char Normal Shift Ctrl Alt Rubout BackSpace_Key Ctrl_BackSpace_Key Enter Enter_Key Ctrl_Enter_Key Tab Tab_Key Escape Esc_Key Back Tab Back_Tab_Key Up Arrow Up_Arrow_Key Down Arrow Down_Arrow_Key Right Arrow Right_Arrow_Key Ctrl_Right_Arrow_Key Alt_Right_Arrow_Key Left Arrow Left_Arrow_Key Ctrl_Left_Arrow_Key Alt_Left_Arrow_Key Home Home_Key Ctrl_Home_Key Alt_Home_Key Page Up Page_Up_Key Ctrl_Page_Up_Key Alt_Page_Up_Key Page Down Page_Down_Key Ctrl_Page_Down_Key Alt_Page_Down_Key End End_Key Ctrl_End_Key Alt_End_Key Delete Del_Key Alt_Ins_Key Insert Ins_Key Alt_Del_Key The JORF Manual (Shareware Disk Version) 338 Appendix D The JORF.INI File The JORF interpreter uses a Windows style INI file to set initialization values. For the DOS version, the file name is JORF.INI. The windows version uses a file called JORFWIN.INI. Compiled JORF applications have use a file with the same name as the program, with the extension "INI". Thee new version of EDITINI.J allows you to set many of these features. This appendix exists as a reference to each setting. There are three major sections of the ini file. The first section controls operating options and video handling. The second section controls printers, and the final section controls screen colors. INI Operating Options These options control how the JORF interpreter operates. Only the first four letters of the command are used. You will notice that most options only affect DOS systems, and not Windows systems. BIOS=No DOS Only Use Bios Screens Mouse=Yes DOS Only Use Mouse if available Scroll=Yes DOS Only If No - doesn't use scroll Explode=3 DOS Only Speed of display Mono=No DOS Only Use Mono colors Multiuser=No Yes for Network Access Mem Stats=No Memory Details Ram Disk=E:\ Use Ram Disk BIOS=No DOS Only. Using BIOS video display is the official way to handle video functions on IBM PC computers. Many of the BIOS routines are very slow, however, so JORF usually uses direct video access. Some computers, notably EGA systems, have enough differences that the video display is really whacked out. If this happens, try setting BIOS=Yes to see if the video starts working properly. Mouse=Yes DOS Only. The JORF interpreter will know if you have a mouse active. Some mice may have problems, so this is a way to turn off the mouse in JORF so you can still have a mouse driver loaded. Appendix 339 Scroll=Yes DOS Only. I recently had a case where I suspected a specific VGA card did not handle the BIOS scroll function properly. Although the use of this function speeds scrolling, it is not required so I created an option in case you also suspect a problem with scrolling. You should note that JORF uses the scroll function primarily to clear the inside of windows. Explode=3 DOS Only. Exploding windows are a cute feature found in the DOS version of JORF. An exploding speed of 3 seems about right for the right video affect. Some people dislike this, and should set this to be Explode=0 to have windows display without exploding. Mono=No DOS Only. Monochrome video override. Normally JORF knows whether you have a monochrome or color monitor. Some people have portables with monochrome monitors that display shades of gray. On these monitors the appearance of JORF may be enhanced if you set Mono=Yes to force the system into monochrome mode. Multiuser=No DOS and Windows. This one is really important. If you want to have multiple access to a file, you must set Multiuser=Yes. This includes access on DOS systems when you are using a program switcher like Software Carousel, and also multiple access using Microsoft Windows. As soon as you switch Multiuser=Yes you must also take other action. First, you must load SHARE.EXE so that JORF can properly lock the files. You will get a nice message if you do not have share loaded. You should also have a disk cache program like SMARTDRV running, because JORF does a lot more file IO in multiuser mode (It must rewrite the file header after every file activity) Even with a cache program running, JORF is just not as fast in multiuser mode as it is in single user mode. Decimal=. DOS and Windows. Some countries use the comma to mark the decimal point, and the period to mark thousands. If you wish to use this notation, change the Decimal entry to "Decimal = ,". Decimal = . 1,234,567.89 Decimal = , 1.234.567,89 When you change decimal indicator to a comma, all numbers that the operator enters must be in comma decimal format. However, all numbers and number formatters in the program code must be in American (period decimal) format. This includes the characters in a the number formatter used by Num:Str. When you change the decimal indicator to a comma, all numeric values that were written to file as numbers will be changed. The JORF Manual (Shareware Disk Version) 340 However, numeric values that were written to the file as strings while the decimal indicator was a period must be translated. To translate a number stored as a string from period decimal to comma decimal, use the To:Num function. Programmers who wish to keep their programs internationalized will take care to avoid storing numbers as strings. JORF normally stores numbers as numbers, so you don't really have to worry, just don't try to override the default numeric format. Mem Stats=No DOS and Windows. This option turns on memory statistics reporting that I use to help me debug the memory swapping system. When you turn this mode on, your program will run very slowly. Every memory allocation and deallocation will be registered, so when the program ends it can report any un-deallocated buffers. You will note that usually the ending is silent, which means that I am successful in my goal of deallocating every single buffer that I allocate. This mode also makes flushing more apparent, and displays the currently open file. Ram Disk=D:\ DOS and Windows. Since JORF uses a swap file, you can optionally place this file on a RAM disk. The RAM disk should be more than 100K in size, and is best at 512K or larger. There is no control if the Ram disk becomes full and the errors will probably be really ugly. The largest items in the swap file are screen backgrounds, but also misspelled text, the program stack, and other space bits may appear here. On multiuser systems, you may also use this to point to a local drive for the swap file. INI Printer Set Up When distributed JORF programs come with my printers. You can easily change them to be your own by modifying the printer set up. Printer definitions are simple: The entire line is displayed on a printer selection menu, and the last word is the printer designation. Printer = Screen, SCREEN Printer = File, FILE Printer = HP Laser, COM1: Printer = Panasonic, LPT1: The options for SCREEN and for FILE invoke special features in the File:Print function to display the file on screen, or rename it to a special file name. To print to a printer, you the last word of the command must be PRN, AUX, LPT1, LPT2, COM1, or COM2 to indicate default printer, auxiliary, line printer one and two and serial printer one and two respectively. Appendix 341 Under DOS, the different printing mechanisms are distinct. The easiest and most robust is to print to PRN, the default printer. To test to see if your printer is working, use the DOS PRINT command to print a small file. The next most robust is LPT1 and LPT2. These use a different BIOS call than PRN so they may not work even when PRN works just fine. These commands send output to parallel printers. Parallel printers may be identified by having a thick cable and a bigger-than-normal connector on the printer end of the cable. Under Microsoft Windows, you must reference a printer that you have set up under windows. JORF automatically searches your windows printers, and will not be able to print to a port without a windows printer set to that port. INI Window Colors The final section of the JORF.INI file handles the colors and style of the windows. This section is more extensive in the DOS version, but also exists in the Windows version. The colors I supply are specifically related to the mathematical values of a pixel on a color monitor. Unfortunately these colors, especially background colors, are pretty ugly. You see what you can do, and compare to other applications that you like to use. Colors are tied to a window background structure that has a name. The name is set in the first line. JORF uses some special backgrounds for specific types of windows. Error boxes use "Error", Message boxes use "Message", and Menu boxes use "Menu". You can also specify custom backgrounds using a window structure in the Win:Add function. The default background is "Text". Window=Text Background name "Text" +Mono/Color=Mono Normally "Mono" +Line Style=double Thick,Double,Single,None +Border Color=For/Back DOS Only Border Color +Title Color=For/Back DOS Only Title Color +Shadow Color=For/Back DOS Only Shadow Color +Message Color=For/Back Message Color +Normal Color=For/Back DOS Only Attribute 1 +Low Color=For/Back Attribute 2 +Medium Color=For/Back Attribute 3 +High Color=For/Back Attribute 4 +Bold Color=For/Back Attribute 5 Window=Text DOS and Windows. Sets the name for this window background structure. All options within this structure start with a plus (+) sign. The JORF Manual (Shareware Disk Version) 342 Mono/Color If you wish, yo u can set up separate definitions for monochrome and color monitors even if they have the same name. Line Style= Sets the border line style. The style can be Single, Double, Thick, or None. Even if you set None there will still be a border, but it will be made of space characters. Border Color= DOS Only. Sets the color for the border lines, but not the title at the top of the window. The mouse "Close block" is also drawn using the border color. Under Windows the border color is a system control. Title Color= DOS Only. Sets the color for the title. Under windows this is a system control. Shadow Color= DOS Only. Sets the color for text in the shadow of a window. Under windows there are no shadows. If you set this to nothing, no shadows are displayed. Message Color= DOS and Windows. Sets the color used by the Win:Msg function for messages. Normal Color= DOS and Windows. Sets the color used by normal text in the window. Low Color= DOS and Windows. Sets the color used by Win:Att(2), and also by inactive menu option letters. Under windows, pull down menus use the default system colors. Medium Color= DOS and Windows. Sets the color used by Win:Att(3), and also by lines within menus and group boxes. High Color= DOS and Windows. Sets the color used by Win:Att(4), and also by active menu lines, and inactive input fields. Bold Color= DOS and Windows. Sets the color used by Win:Att(5), and also by active menu option letters, and active input fields. Appendix 343 Foreground Colors Black Blue Green Cyan Red Magenta Brown White (Gray) Gray (Darker Gray) Light Blue Light Green Light Cyan Light Red Light Magenta Yellow Bright White Background Colors Black Blue Green Cyan Red Magenta Brown White (Gray) *Gray (Darker Gray) *Light Blue *Light Green *Light Cyan *Light Red *Light Magenta *Yellow *Bright White * These background colors cannot be displayed on CGA monitors. Instead, the color will blink and be really obnoxious. Be certain your user is using EGA or VGA before using these colors. The JORF Manual (Shareware Disk Version) 344 Appendix E - JORF Errors JORF Errors The following is a list of JORF errors. When an error is displayed, the offending program line is also displayed. If there is a DOS error to report, it is reported. In this list, the module name is identified. This is my own reference, and has little meaning except to group errors with a task. (For instance, all errors with a module of JDB relate to dBASE file functions.) Some errors are marked Info. These errors are considered debugging tools, (for when I am debugging the interpreter) and will not be displayed unless you have Mem Stats=Yes in your INI file. Some errors are marked Fatal. These errors will cause the program to abort. They cannot be trapped by any error system. They are generally initialization errors (Not enough DOS memory, cannot Init CGA driver). The rest are memory or data corrupt errors that you should never see. If you create a program that corrupts memory and produces a fatal error, please send that program to me with instructions on how to reproduce the error. My goal in JORF is to make it impossible to produce a fatal error. (As opposed to Clipper where every error is fatal, even something so trivial as a type-mismatch.) Appendix 345 Error Module Description 101 JCLASS Could not delete method METHODNAME 102 JCLASS Could not delete method METHODNAME Method:Del was called, but the indicated method was not indexed in the JRF file. 103 JCLASS Can't read FILENAME Unable to read file. See DOS error message. 105 JF Cannot open file FILENAME Unable to open file. See DOS error message. 106 JF File FILENUMBER not found. A record referenced a file by number, that file was not found. Files are numbered according to when they are opened. File one is always SWAPFILE.JRF where the program stack and temporary variables are stored. File two is the start-up program file. The common reason for this error is that a record number was corrupted in memory. Since the JORF language does a lot of memory operations, memory variables are particularly susceptible to this kind of problem. One thing that I know makes this error happen is trying to read and allocate many strings greater than 10K in size. For some reason, the Borland MALLOC fails (or I fail in some way) when you allocate and deallocate 20K far buffers more than about 50 times. Since the JORF File read routines are constantly converting buffers into JORF pointers (thereby allocating memory) this causes this malloc problem to appear. There may be other causes, and I am always striving to insure that this error never happens. If you can make it happen "on-call", please send me the program so I can fix the problem. Thank-you. 107 JF - Info File 0 error record NNN Same as 106 except that the record pointer is zero. The JORF Manual (Shareware Disk Version) 346 Error Module Description 108 JF - Info Delete root not deleted in FILENAME 109 JF - Info Delete root not deleted in FILENAME 110 JF - Info Bad delete root in FILENAME These three errors appear if the program locked up in single user mode. In this mode, file headers (and the delete root) are not written until the program terminates normally. Since the program did not terminate normally, the delete root is incorrect, and the error is simply a message that the delete list will be restarted. No data is lost, just deleted buffers will not be recovered until the next pack operation. These errors are INFO errors, meaning that they will only be displayed if you have Mem Status = Yes in the INI file. Because no data is lost, I felt it was not necessary to display the error normally. Having this error occur on a file that was closed properly means that the information written to file is corrupt, which is a true error, but corrupted files will exhibit other errors that will be reported. 111 JF - Fatal Illegal record flag at POS in FILENAME Corrupted file. If this is a program file, erase the JRF file and reload from the source. If this is a data file, rebuild the file using the -R flag: JORF CLASSNAME -R FILENAME The CLASSDEF must be the program file that contains the class definitions for the indexes. There may be more than one CLASSDEF file, and these files are not rebuilt. Every file named after -R is rebuilt. 112 JF - Info Attempt to read deleted record in FILENAME Normally you don't see this because it is an INFO error. However, I have found some combinations of array pointers to structures, and structure pointers to arrays, where the automatic garbage collection function during the flush operation was deleting a little too much data, and the symptom was this error when the program tried to reference the cleaned data. If you have a recurring case where this is a problem. Please send me the program. Thank-You. Appendix 347 Error Module Description 113 JF File FILENAME not locked Record locking must not be working properly on your system or network. Please contact me to help me get the locking working correctly. Naturally, I have been too poor to buy every network to test this product. 115 JF - Info Record 0 Error in FILENAME Data corrupt, see 106. 114 JF File FILENUMBER not found Data corrupt, see 106. 116 JBLOCK Can't read FILENAME Block read, incorrect file name. See DOS error. 117 JBLOCK Can't open FILENAME for block write 118 JBLOCK Can't write block to FILENAME Block write, could not open. See DOS error. 119 JBLOCK Unknown Win:Block command COMMAND See reference guide for valid command strings. 121 JCLASSDI Can't write to DATAPATH Attempted to write program file, but couldn't. See DOS error. 122 JFILE - Info Can't free FILENAME Unable to clean up after method that accessed a new file. I've never seen this one, and you shouldn't either. As usual, if you see this at all, please send me the program so I can investigate. May be a memory corrupt, see 106. 123 JFILE Can't open file FILENAME Could be illegal character in the name, or a sharing violation. See DOS error. 128 JFOPEN Can't close file FILENAME Tell me. Should never happen. See DOS error. The JORF Manual (Shareware Disk Version) 348 Error Module Description 129 JFRENAME Cannot rename file FILENAME Probably illegal character or sharing violation, See DOS error. 130 JFOPEN Cannot back up file FILENAME File:Backup failed, see DOS error. 131 JFOPEN - Info Cannot unlink file Memory corrupt? See 106. 133 JFOPEN Could not read file buffer length LENGTH 134 JFOPEN Could not read file buffer length LENGTH See DOS error. Mostly indicates a case where the program wants to read 512 bytes, and DOS only gives back 422 bytes or something. 135 JFOPEN - Info Cannot resize file FILENAME Could not reset size of file. See DOS error. 136 JFOPEN - Info Seek error byte POS 137 JFOPEN - Info Cannot seek to byte POS in file FILENAME 138 JFOPEN Cannot seek file FILENAME Usually memory corrupt (see 106) causes a record pointer to come out with an outrageous record position (like 100 gigabytes past the beginning of the file). The Position is the seek-to position, so you can see whether this is the case. I have also seen this error in cases where a program deleted an active data file while there were active pointers to that file. Appendix 349 Error Module Description 139 JFOPEN Record size SIZE is too long, limit MAX in file There is a limit to the largest buffer you can read in JORF. It changes, and is closely linked to my problems with Borland Malloc/Free failing when you thrash around with buffers greater than 10K. For that reason, 2.1 is shipping with a max file buffer size of 10K. However, if Borland fixes this problem, I want to increase the buffer size to 32K. If you need to read a large buffer, why not find a way to map the file into 5K chunks and read in 5K segments. 140 JFOPEN Cannot Read in file FILENAME. We asked DOS to read 512 bytes, but DOS only gave us 422 or some other number. See DOS error. 141 JFOPEN Record size SIZE is too long, limit MAX in file Same as 139 except this one is when you are writing a file. 142 JFOPEN Cannot write to file FILENAME Same as 140 exept when writing a file. See DOS error. 150 JINI INI: Unknown color COLOR See Appendix D for legal color names. 151 JINI - Fatal INI: Unknown command COMMAND 152 JINI - Fatal INI: Equal sign required COMMAND 153 JINI - Fatal INI: unknown command: COMMAND The first thing the program does is read the INI file to get settings. In this case, there was an incorrect command in the INI file. You will have to correct the displayed command. 154 JINI - Fatal INI: Cannot read file FILENAME If the file were simply not found, a default INI file is written and no error appears. This error indicates that the INI file is there, but somehow locked so it cannot be read. See DOS error. The JORF Manual (Shareware Disk Version) 350 Error Module Description 155 JINI - Fatal INI: Cannot use multiuser mode without SHARE.EXE. 156 JINI - Fatal INI: To run another instance of JORF you must set 'Multiuser=Yes' in the INI file These two are related. The second appears under Windows if you try to load the same JORF module twice. The first appears if you try to run Multiuser = Yes without SHARE.EXE loaded. If you want to run in multi-user mode, you must load SHARE. See your DOS manual for further instructions on SHARE. 157 JINI - Fatal INI: Cannot write file FILENAME When no INI file is found, a default INI file is written. This error means that you do not have write permission on the current directory. Check your network rights. 200 JM - Fatal Cannot load cache Ran out of memory on a very basic start-up operation. Check memory. 201 JFLUSH - Fatal Cannot reload memory 202 JFLUSH - Fatal NDEL buffer exceeded These are equivalent to an out-of-memory in a language like C. In this case, the virtual memory system's tables are being exceeded because you have a) too deep a stack, b) too many items in the stack, c) too many functions compiled in a application or d) something else. While I have tried to adjust these tables so that you will never see these errors, the can occur and that means the table sizes need further adjustment. Naturally, I want this program to work for you. If you see either of these errors, please send me the program and I will try to adjust the table size to accommodate your needs. 220 JDB Cannot create index NTXNAME Probably a bad file name or sharing violation, see DOS error. 221 JDB File FILENAME is not dBASE III JORF cannot handle dBASE IV files. Appendix 351 Error Module Description 222 JDB File FILENAME not mapped in function You attempted a DB operator without mapping the file as a dBASE file. The mapping is required before you can read or write to a dBASE file. 223 JDB File FILENAME not found. Use Db:Create to create it. File not found. 224 JDB Cannot open FILENAME File was found, but could not be opened. Locking? Out of handles? See DOS error. 225 JDB Cannot find file DBTNAME 226 JDB Cannot open file DBTNAME Found the DBF file, but not the matching DBT file. Whenever you copy a DBF with memo fields, you must also copy the DBT file. 227 JDB NTX Order number too high Attempt to DB:SetOrder to an index number too high. If you have three NTX file, you cannot DB:SetOrder(4) because there is no NTX number four. That is all. 228 JNTX Underflow count COUNT at POS 229 JT Underflow count COUNT at POS File corrupt. In error 228 it is with an NTX file. In error 229 it is in a JRF file. The file must be rebuilt. 280 JPACK Can't write to pack file FILENAME 281 JPACK Can't read pack file FILENAME Problems during JORF Rebuild. See DOS error. 282 JPACK Can't find count in pack file FILENAME. Problems reading pack file, or pack file is wrong format. See DOS error. 283 JPACK Cannot rebuild swap file The SWAPFILE.JRF file cannot be packed. The JORF Manual (Shareware Disk Version) 352 Error Module Description 284 JPACK Cannot rebuild active program To rebuild a program file, write the source, erase the JRF file, and the interpreter will automatically re-read the source. You cannot rebuild a source file using JORF:REBUILD. 301 JCALL Too many ops In a compiled application a JMATH() call had too many operations. Please keep each math expression simple. 302 JIF Misplaced 'else' Found ELSE with no matching IF statement. 303 JIF Use "thru" not "to" 304 JIF Bad syntax for "=" in For function 305 JIF Missing value ENDVALUE in For function 306 JIF Lost value ENDVALUE in For function In a FOR () statement there was a syntax error. Basic programmers will get the first one a lot, until you understand how incorrect "To" can be. (When you say For (i = 1 to 10) do you mean to end at 9 or 10?) 310 JFMAP Illegal file map type MAPTYPE See reference section for File:Map for list of legal file types. You must have misspelled something here. 312 JFMAP Missing file map for FILENAME A dBASE file requires a map before you can create it. You can read the file without a map, because the file will be mapped from the file header, but you cannot create a file you have not yet defined. 313 JFMAP Map width WID is too long, limit MAX in file. There is a limit to buffer size. See Error 139. Appendix 353 Error Module Description 320 JMALLOC - Fatal Out of Memory Dead! The virtual memory system should keep this from happening. Getting this error means that you have circumvented the automatic heap checking system and caused the program to allocate more memory than is available. Check DOS memory. If you have only 540K or less free, you can probably fix this by clearing enough AUTOEXEC stuff to get 560K free. Try removing ANSI.SYS, and any TSR programs that use a lot of memory. Under DOS 5.0 you can examine memory using the MEM command (see your DOS manual). If you have a known operation that will use a lot of memory (like reading a 10K record buffer) you may want to do a partial memory flush ahead of time. Try Jorf:Flush(50) before this operation, to flush memory if there is not 50K available. The reason you may need 50K is that the buffer takes 10K, when the buffer is turned into a JORF pointer uses 10K, and 30K free space is not unreasonable for the other tasks like executing the next program line or calling another function. 321 JMALLOC - Fatal Address zero changed I usually compile this one out before distribution, so you will not see it. Because JORF is written in C, and null pointers in C cause address zero to change, I have a running check of the value to make sure JORF is well behaved. The JORF Manual (Shareware Disk Version) 354 Error Module Description 324 JMALLOC - Fatal Cannot unlink memory! 325 JMALLOC - Info Bad free offset from LOCATION 326 JMALLOC - Info Buffer already freed: LOCATION at LOCATION 328 JMALLOC - Info Buffer overrun: LOCATION at LOCATION To see any of these you need Mem Status = Yes in your INI file. These are things I watch as I develop each command, to try to ferret out memory corruption problems. With Mem Status = Yes the Malloc buffers are linked into a list, so that when the program ends I can be sure that every buffer has been freed (a sign that all buffers are written properly.) the Cannot Unlink error used to mean that a buffer was allocated wrong, but lately I only see it associated with general memory corruptions caused by reading 20K buffers from file. (Shrinking the max buffer size eliminated the problem, hence the limit in Error 139) Compiled Windows Programs exhibiting these errors should check the STACKSIZE command in the DEF file. These errors are a symptom of a stack/heap crash, and shrinking the STACKSIZE may help this problem. All Mallocs and Frees under JORF are labeled with short strings for identification, so "Buffer Already Freed JARR at JFR" tells me that the buffer was allocated as a structure (JARR) and was being deallocated by the general JORF Pointer free routine (JFR). This system helps me track memory problems. 329 JMALLOC - Fatal Out of Memory Same as 320 except with near heap, not far. 330 JMALLOC - Info Buffer already freed: LOCATION at LOCATION 331 JMALLOC - Info Buffer overrun: LOCATION at LOCATION Same as 326 and 328 except with near heap, not far. 332 JMALLOC - Fatal Insufficient DOS Memory You gotta have 560K free to run JORF well. On an old XT computer, you need to be running DOS 3.3 or lower with few TSR programs. On AT and 386 computers, you need to load DOS high to free up enough memory. Appendix 355 The JORF Manual (Shareware Disk Version) 356 Error Module Description 334 JARRINI Cannot exceed WORDMAX elements in structure or line There is a limit to the number of elements in a structure. I change it around, but currently it is 256 or 512 depending on my mood. A structure can always point to a sub-structure to increase the number of elements infinitely. 401 JWRITE Attempt to write stack You got some mixed up pointer here. Tell me how you did it. 402 JWRITE Bad flag in newcopy Probably a file corruption. Rebuild it. 404 JREAD Lost text top Text is sparse in memory. This means that in memory is the current line of text, and the top line of text, but maybe not all lines in between. This system allows access to text that is longer than available memory size. Something has happened so the current line is still available, but the top line has been deleted. Tell me how you did it, and I will fix it. You should never see this error. 405 JREAD Bad record 406 JREAD Bad word count Read a record from the data file and it was not what it should have been. Something has overwritten this part of the file or something. Try rebuilding. 408 JREAD Cannot read line LINEPOS of text Something has happened to text where a line does not exist. This is pretty difficult, and may be related to a data corruption. Use to be you could do this by block moving or deleting so that the text was really shifted around. This should all be fixed now. If not, tell me. Appendix 357 Error Module Description 602 JMARRAY Illegal brackets for array 604 JMARRAY Missing [ in array Array index must have one [ left bracket and one ] right bracket. 605 JMBINARY Illegal unary operation Unary operations are ++a, --p, or negation. You tried something that is not legal. Stick to the legal ones please. 606 JMARRAY Not an Array 607 JMENUARR Not an Array in "Arr:Pick". Arr:Sort and Arr:Pick require arrays. One way to check before this error appears is to be sure that Arr:Len is greater than one. 702 JA Unable to move SOURCE to DEST Some problem with the obscure Jorf:Move function. 708 JFNC Can't find Class: CLASSNAME Class definition is not found in any of the currently opened files. 710 JA Can't find METHODNAME Method is not found in any of the currently opened files. 711 JA Attempt to seek null element in class CLASSNAME The Member label is null for some reason, like to said A->"" = B or something. 712 JA Element MEMBERNAME is not a member of Class CLASSNAME 713 JA Element MEMBERNAME is not a member of Class CLASSNAME Attempt to assign a member that is not in class defintion. Only the JORF class can take any member name, other classes must have all members declared in the class definition. 714 JA Attempt to seek null element in class CLASSNAME See 711. The JORF Manual (Shareware Disk Version) 358 Error Module Description 715 JA Assignment of stack See 401 716 JA Element MEMBERNAME is not a member of Class CLASSNAME See 713 716 JCPY Bad word data Some kind of memory corruption. This one is usually pretty regular. Please send me the program, because this can be easily fixed once I see how you produce it. 721 JMAGIC Mismatched brackets in EXPRESSION Curly brackets must be in sets. To print a curly bracket with magic on, print it as a constant {"{"}. 722 JMAGIC Exceeded buffer size (512 Bytes) Buffers with curly brackets cannot be longer than 512 bytes. 720 JTRACE Too many break points You can only set about 10 break points while debugging a program (or is it 20? can't decide). Try unsetting one or two. 723 JPARSE Mismatched parentheses: EXPRESSION Expressions must have matched parentheses. 730 JWPARSE Unknown window item ITEM Perhaps you window definition got so long that you got confused and did not outdent the next program line. 731 JWPARSE - Fatal Exceeded count Unlikely to ever see this, but it has to do with the count of prompted items in hypertext. Send program if you see this at all. I will fix. 741 JI Unknown variable or method LABEL Appendix 359 Couldn't even decide if this is a Method, Variable or Function call. The JORF Manual (Shareware Disk Version) 360 Error Module Description 742 JI Don't know how to COMMAND Decided this was a Method or Function, but don't know how to call it (cannot find it). 743 JI Too many parameters (limit 10) in function call Currently a limit of 10 parameters. 744 JI - Fatal Lost name, now METHODNAME A speed optimization has gone awry. Send me the program. 745 JI Cannot find method METHODNAME Program knows it is a method, but cannot find it in any of the currently opened program files. 747 JI New is not at method top New() must be the first line of the method. 801 JMESSAGE Unknown message type MESSAGETYPE See Msg:Add for list of valid types. 802 JS Can't set attribute ATTRIBUTE See Win:Attr for valid Attribute syntax. 805 JS Can't set justification FLRCO See Win:FLRCO for valid FLRCO letters. I'll give you a hint - they are F-L-R-C and O! 808 JSADD Too many windows, limit 512 Mike B. Memorial error message. His first program displayed 3000 empty windows, ran out of memory. Limiting to 512 windows "fixed" the problem. 809 JSINP Input line too long (512 character max) Single line inputs cannot exceed 512 characters. Appendix 361 Error Module Description 812 JSL - Fatal Graphic error: GRAPH_ERR_MESSAGE The GRAPH_ERR_MESSAGE should tell you more. Usually a missing BGI file or something. Only the VGA driver is compiled into the JORF386 program, so if you are using 8512 or SVGA there could be problems in graphics mode. 813 JSLBKD - Fatal Cannot allocate background buffer You know there is a lotta bits in a graphics window, so when storing the background buffer the program must malloc and free some big buffers. If there is a mis-allocation, you will see this error. Try to run with more free memory. 814 JSLBOX - Fatal Out of windows memory Actually, not memory but just displaying problems. Could not create a new window. 820 JSLCARET Attempt to create caret without focus Isn't Windows lingo fun? Just tell me how you did it and I will try to fix it. It is, naturally, illegal to create your caret if you don't have focus. 821 JSLCARET - Fatal Image size too large The blinking cursor image is bigger than the image buffer. I am making the buffer big enough now for all known cursor sizes, so if you see this, I will need to go bigger than that. (Tell me what you have - Super Super VGA?) 82 JSLCARET Attempt to destroy caret without focus See 820. 823 JSLFLUSH Call to DestroyWindow failed Microsoft nicely document that DestroyWindow can fail, but did not say why. The JORF Manual (Shareware Disk Version) 362 Error Module Description 824 JSLVMODE - Fatal Could not register driver 825 JSLVMODE - Fatal Could not register driver 826 JSLVMODE - Fatal CGA graphics not supported 827 JSLVMODE - Fatal PC3270 graphics not supported 828 JSLVMODE - Fatal IBM8514 graphics not supported First of all, you have GRAPHICS=Yes in your INI file. You can make these errors go away if you set the INI back to GRAPHICS=NO mode. Second, only VGA graphics is currently supported by an internal driver. If you need CGA or 8514 graphics, you must put the appropriate BGI driver on your JORF directory. BGI drivers are supplied by Borland in their Turbo C++ and Borland C++ products. 910 JPRINT Can't print to PRINTER 911 JPRINT Couldn't access PRN 912 JPRINT Printed incomplete string to PRN 913 JPRINT Invalid LPT Printer 914 JPRINT Printer timed out 915 JPRINT Printer out of paper 916 JPRINT Invalid COM Printer 917 JPRINT Can't Print to COM 918 JPRINT Unable to access windows printer PRINTER 919 JPRINT Cannot print file FILENAME See DOS error, check printer name. 920 JREPORT Unknown Report Item ITEMNAME See Reference section for Rep:Add. The parser encountered a command that is not valid. 921 JREPORT Cannot open JREPORT.LST All reports are written to an output file called JREPORT.LST. Something is keeping this file from being created. See DOS Error. Appendix 363 Error Module Description 1101 JSYSTEM Process is busy 1102 JSYSTEM Cannot register Exec class 1103 JSYSTEM Cannot create Exec window 1104 JSYSTEM Cannot register notify proc 1106 JSYSTEM Cannot find Exec task handle 1107 JSYSTEM Error executing "COMMAND" Windows did not how I set up the Jorf:System() command. Please tell me what you are trying to run, and I will try to investigate. I program Windows, but I don't have to like it. 1110 JSYSTEM WINDOWS_MESSAGE executing: COMMAND Windows did not like your Jorf:System() command. Hopefully the MESSAGE it gives back will tell you what you need to know. Here is a list of messages: Out of memory or Exe file corrupt File not found Sharing error Library required separate data segments Out of memory Incorrect Windows version Invalid Executable file App was designed for a different Operating System App was designed for MS-DOS 4.0 Type of Executable file unknown Cannot load a real-mode application Cannot load this program twice Cannot load compressed EXE file DLL file invalid or corrupt App requires 32-bit extensions Windows Exec error The JORF Manual (Shareware Disk Version) 364 Appendix F - DOS Errors DOS Errors The following is a list of DOS errors. DOS errors are almost always related to "Device" operation, like reading from a file or writing to a printer. This list is standard for all versions of DOS, but there may be differences in the higher numbers on some networks. Error Description 2 File Not Found File is not found or file name contains illegal characters so that the file is not found. Another possibility is that the specified file is a directory name, and not a complete file name. 3 Path Not Found Path does not exist as specified. Could be illegal characters, but more likely to be a problem with pathing from the root. 4 Too many files This is directly related to your FILES= command in CONFIG.SYS. That command designates a static buffer for all the handles for files open simultaneously on your computer. Running a program opens three handles, one for STDIN, one for STDOUT, and one for STDERR. Each additional open file uses one handle. If you get this error, the simplest solution is to increase your FILES= number to 51 if it is lower, 99 if it is already 51, or 254 if it is already past 99. Do not increase it beyond 255, DOS limit. The handles are very small, so adding more handles does not affect your DOS memory very much. You should never see JORF report this error, since it can selectively close files if you run out of handles. However, if this is the case, you can vastly improve performance by increasing your files to a number high enough to handle all the open files in one application. Appendix 365 5 Access Denied You do not have sufficient privileges to access this file. In normal DOS, check ATTRIB (See your DOS manual). Under a network, check your logon permissions. Also check to see if someone is using the file (Can't erase a file someone else is using). 6 Insufficient Memory I've never seen DOS report this, and suspect it is as old as a 64K IBM PC computer. 15 Invalid Drive Specified Can't specify D: if you have only A:, B: and C:. 21 Drive not Ready Close the door to your floppy disk drive. 29 Write Fault 30 Read Fault 31 General Failure Diskette may be write protected, corrupt or not formatted. It may be the wrong density for the drive. It may be a Macintosh disk. 32 Sharing Violation Someone has this file in use at the same time as you tried to delete it. 33 Lock Violation Someone has a record locked in this file and you tried to delete it. The JORF Manual (Shareware Disk Version) 366 Index .JRF files 9 Button Handling 12 Absolute Value 223 By reference 5, 6 Accelerator 55 By value 5 Add Watch 26 Cancel 21, 23 Add dates 105 Capitalize String 287 Add Method 23, 215 Chaining 172 Add Time 278 Chaining, Program 172 Addition (+) 33 Change After 57 Window Fields 312 Alt-F4 Key 54 Character Append Record 142 Delete 97 Append to dBASE file 115 Get 35, 39, 41-43, 49, Array 58 98 Delete 86 Insert 99 Directory 87 Print 157, 186 Insert 90 Put 100 Length 91 ChBox 62 Pick 93 Check Box 62 Printers 94 Class Sort 95 At 101, 322 Arrays 7, 194 AtDelete 323 Arrow Keys 53 AtInsert 324 ASCII file conversion 151 AtPut 103 ASCII Value 286, 288 In 104, 326 Assignment (=) 34 Classes 7, 22 Attr 56 Clear Screen 168 Autowatch Off 30 Clipper Files 10 Autowatch On 29 Clock ticks (Time:Ticks) 285 Backup File 143 Close file 117, 145 Before 57 Colors 342 Between numbers 224 COM port access 258 Binary Files 160 Comma BINARY.J 5 Decimal 340 BIOS Screen Display 339 Comma decimal 235 Block Copy 311 Comma decimal numbers 295 Block Read 311 Continue 299 Block Write 311 Controls 339 BOF in dBASE file 121 Convert Date 113 Break 299 Convert time 282, 296 Browser List 93 Converting files 123, 151 Buffers 11 Copy Button 63 Structures, Text 171 Appendix 367 Copy File 146 Jorf Pointers 169 Create dBASE file 118 Line 209 Create NTX index 118 Method 24, 216 Ctrl-Break Structures 169 Starting the Text 169 debugger 13 Delete Watches 29 CUA standard 54 Delete Array elements 86 Cursor Position 219 Delete dBASE record 119 Data Base Manager 7 Deleted record status in Data Fields 12 dBASE file 121 Data files 9 Developer's Kit 13 Date Dialog Box 217 Add 105 Directory 87 Formatting 113 Directory List 135 Get 109 DirList.J 59 Set 110 Disk space 176 Set Format 111 Display 57 String 113 Display String 259 Subtract 114 Division (/) 36 Date conversion 289 DLM format files 151 Day of Week (Date:Str) 113 Do Line 27 Db DOS Environment 176 Append 115 DOS Errors 365 Close 117 DOS Shell 190 Create 118 DOS Version 176 Delete 119 Dos.J 191 Go 120 Duplicate Info 121 Structures, Text 171 Lock 122 Edit 20, 23 Map 123 Editing Keys 30 NtxOrd 126 Editing Outside 13 Pack 127 EditKey Class 52 Read 128 End of File 156 Recall 129 Environment Values 176 Seek 130 EOF in dBASE file 121 Set 131 Equality (=) 37 Skip 132 Error Undelete (Recall) 129 Event 136, 140 Unlock 133 Error Messages 345, 365 Write 134 Event dBASE Conversion 123, 151 Add 136 DBASE/Clipper files 10 Delete 138 Debugger 13 Do 139 Starting 13 Exit 22, 172 Debugger Keys 30 Explode time 340 Decimal format 235, 295 Exponent 225 Decimal numbers 295 F1 Key 54 Decmial False 141 setting in INI file 340 File Decrement (--) 35 Access 144, 148 Delete Append 142 Character 97 Backup 143 The JORF Manual (Shareware Disk Version) 368 Check existence of 144, Increment (++) 38 148 Index - Current (dBASE) 126 Close 145 Indexes 7 Conversion 151 Indexing Copy 146 Structures 8 Delete 147 Inequality (!=) 39 Directory 87 Info about JORF/DOS 176 Directory list 135 Info in dBASE file 121 Exist 148 Initialization 339 Length 149 Initialization File 177, 339 Load 162 InpAfter 57 Map 151 InpBefore 57 MoveTo 155 Input Fields 68, 71 New Project 173 Insert Number of JORF files Character 99 in use 176 Line 211 Ok 156 Insert Array 90 Print 157, 186 Installation i Read 160 InString 254 Rename 161 Integer Save 162 Between 224 Write 163 Maximum 227 File Load 150 Minimum 228 Finish 27 Integers 7, 290 Finish Method 28 International numbers 295 Floating point numbers 7 Interpret 170 FLRCO 56 ISA.J Flush Memory 175, 188 Sample Program 242 For loop 164 Jcm2Dbf.J 115 For/Next Loop 164 Jorf Format Date 111 Do (Interpret) 170 Found in dBASE file 121 Duplicate 171 FoxPro 10 Global 214 Free Memory 176 Info 176 Friend 31 Ini 177 Friends 11 INI File 339 Function keys 54 Move 184 Function Reference 331 Printers (Printer Get Date (Today) 109 Set up) 341 Get Time 279 JORF Acronym 1 Getting Started 15 JORF Company 1 Global Values 214 JORF.INI File 339 Go 21, 27 JORFPC 15 Goto dBASE record 120 JORFWIN 15 Greater or Equal To (>=) 41 Josephine T. Goat 1 Greater Than (>) 40 JRF files 9 Group Boxes 65 Justify String Haiku.J 195 (Str:Rpad) 261 Here 166 Key Hotkey 55 Bye 199 Hypertext Prompt 76 Event 136, 139 If/Else 167 Get 200 Appendix 369 Got 201 Structure elements 184 Hit 202 Move Cursor 219 Key lookup dBASE style 130 Moving Structures 11 Keyboard Accelerator 55 MS-DOS Version 176 Keystroke handling 52 Multiplication (*) 48 Last Record 121 Multiuser Status 9, 340 Launch programs 190 Music.J 189 Length of Array 91 Name (Rename) File 161 Less or Equal To (<=) 43 Negation (-) 49 Less Than (<) 42 Negative Numbers 223 Library Function Network Access 9, 340 Reference 331 New 220 Line Next Line 27 Class of Word 328 Next Record Delete 209 dBASE Style 132 Input 210 Next record in file 263 Length 272 Ntx order in dBASE file 126 Output 212 Null 222 Release 213 Null padding a string 256 List (of records) 71 Num Load File 150 Str 340 Lock Record 181 Number in dBASE file 122 Between 224 Logarithm 226 Exponent 225 Logical Formatting 233 AND (&&) 44 Logarithm 226 NEGATION (!) 45 Maximum 227 OR (??) 46 Minimum 228 Lower Case 291 Power 229 Magic 56 Square Root 232 Map dBASE file 123 String 233 Map File 151 Numeric Conversions 233, 292 Math Numeric formatting 233 Method Calls 31 Object Oriented language 22 Mathematics 11 Object Persistence 8 Memory Free 176 Object-Attribute-Value 9 Memory Management 8 Ok 236 Menu Bars 73, 74 Open 20 Menu Lines 75 Order of Operations 11, 32 Menus 12 Other Screen 25 Message Window 217 Pack dBASE file 127 Method Pack Disk File 185, 187 Add 215 Parameters 5 Calls 31 Parentheses 4 Delete 216 Passing by reference 5 Methods and Classes 22 Path (Directory) 87 Modulus (%) 47 Path name 176 Monitor Problems 339 Pick List 58, 93 Monochrome Monitors 340 Power (of a number) 229 Month name (Date:Str) 113 Prev record Mouse Handler 339 dBASE style 132 Move Previous record in file 264 The JORF Manual (Shareware Disk Version) 370 Print 21 Haiku.J 195 Print File 157, 186 Jcm2Dbf.J 115 Printer List 94 Music.J 189 Printer menu (Set up in TextEdit.J 82 INI file) 341 Sample programs Printer set up 341 ISA.J 242 Problems 339 Save 21 Program Chaining 172 Save As 21 Programmer's Workbook 15 Save File 162 Programming Environment 13 Say String 259 Programming Windows 3 Screen Colors 339, 342 Project file 173 Screen problems 339 Prompt 76 Scroll problems 340 Radio Buttons 79 SDF format files 151 Ram Disk 339, 341 Search 321 Random Numbers 230 Seek to a dBASE record 130 Re-Read 22 Sequential Files 160 Read record in dBASE Serial port access 258 file 128 Set Reading files 151 Deleted (dBASE) 131 Rebuild dBASE file 127 SoftSeek (dBASE) 131 Rebuild File 185, 187 Set date 110 Recall dBASE record 129 Set Time 280 Recipe Filers 1 Set time format 281 Record Append 142 SHARE 9 Record Lock 181 Shareware Message 16 Record Unlock 193 Show Variables 26 Reference Show Stack 25 Parameters by 6 Skip record in dBASE 132 Quick Language 330 SMARTDRV 9 Release Input 213 Sort Array 95 Reloading a Project 13 Space pad (a string) 257 Rename file 161 Stack 101 Replace 320 String 80 Replicate After 247 Str:AtSet 253 At 248 Reread 20 AtChar 249 Restart 21 AtCut 250 Return 241 AtDelete 251 Rewind 27, 28 AtPut 252 Right Justify String 261 AtSet 253 Rule Instring 254 Add 237, 242 Length 255 Delete 243 Null Pad 256 Find 244, 246, 262 Pad 257 Next 245 Print 258 Rule Based System 9 Put Line 260 Run 20 Right Pad 261 Sample Program String Key Binary.J 5 Add 204 DirList.J 59 Delete 205 Dos.J 191 Find 206 Appendix 371 Next 207 Upper 297 Previous 203, 208 Today's date (Date:Get) 109 Strings 7 Toggle Break Point 29 Struct Next 263 Trace Forward 28 Struct Prev 264 Translating to C 13 Structures 8 True 298 Blanking elements 184 Type 56 in Data files 9 Undelete a dBASE record 129 Moving elements 184 Unlock a dBASE record 133 Subtract Date 114 Unlock Record 193 Subtract time 284 Upper Case 297 Subtraction (-) 50 Video problems 339 Swap File 339 Weekday (Date:Str) 113 Switch/Case/Else 265, 266 While/Break/Continue 299, 300 System 190 Window Text 7 Add 301 At Line 269 Attribute 309 Class of Word 328 Block 311 First Line 276 Change 312 Justification 315, 316 Colors 339 Last Line 270 FLRCO 315, 316 Length 272 Message 317 Line Number 274 Message Window 217 Next Line 273 Move By 218 Position 274 Move To 219 Previous Line 275 Pause 318 Width 277 Pointer 319 Text Entry 81 Put Line 260 Text File Load 150 Put String 259 Text File Save 162 Replace 320 TextEdit.J 82 Search 321 Time Structure 319 Addition 278 Window colors 342 Formatting 282 Window Manager 12, 51 Get (Now) 279 Windows Set 280 True if running 176 Set Format 281 Windows Features 2 String 282 Windows Settings 56 Subtract 284 Windowstructure 56 Ticks 285 Word Time conversion 296 AtDelete 323 To AtInsert 324 ASCII 286 AtPut 325 Capitals 287 In 326 Character 288 Write Date 289 Item 194 Integer 290 Record 194 Lower 291 Structure 194 Num 340 Write a dBASE record 134 Number 292 Writing files 151 Numeric String 233 Time 296 The JORF Manual (Shareware Disk Version) 372